release: v0.1.17 photo clarity provenance and layout refinements [skip ci]

This reverts commit db0b408680.

.dockerignore

@@ -14,3 +14,6 @@ dist
 .mypy_cache
 **/__pycache__
 **/*.pyc
+
+# macOS metadata at any depth
+**/.DS_Store

.github/workflows/verify.yml

@@ -5,12 +5,6 @@ on:
     branches: ["**"]
   pull_request:
   workflow_dispatch:
-    inputs:
-      deploy_action:
-        description: Production action (deploy requires explicit enabled Variable)
-        type: choice
-        options: [plan, bootstrap, deploy, rollback]
-        default: plan
 jobs:
   verify:
     # The NAS Docker runner must never execute code from external forks.
@@ -47,54 +41,5 @@ jobs:
             python scripts/ci-compose-verify.py --cleanup
           fi
 
-  deploy:
-    needs: verify
-    if: success() && github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
-    runs-on: ubuntu-latest
-    concurrency:
-      group: frame-flow-production
-      cancel-in-progress: false
-    env:
-      CD_ACTION: ${{ github.event.inputs.deploy_action }}
-      PROD_DEPLOY_ENABLED: ${{ vars.PROD_DEPLOY_ENABLED }}
-      PROD_PROJECT: ${{ vars.PROD_PROJECT }}
-      PROD_CONTAINER: ${{ vars.PROD_CONTAINER }}
-      PROD_IMAGE_REPO: ${{ vars.PROD_IMAGE_REPO }}
-      PROD_DATA_DIR: ${{ secrets.PROD_DATA_DIR }}
-      PROD_CONFIG_DIR: ${{ secrets.PROD_CONFIG_DIR }}
-      PROD_PHOTOS_DIR: ${{ secrets.PROD_PHOTOS_DIR }}
-      SYNOLOGY_PHOTOS_URL: ${{ secrets.SYNOLOGY_PHOTOS_URL }}
-      SYNOLOGY_PHOTOS_CERT_SHA256: ${{ secrets.SYNOLOGY_PHOTOS_CERT_SHA256 }}
-      PROD_WEB_BIND: ${{ secrets.PROD_WEB_BIND }}
-      PROD_WEB_PORT: ${{ vars.PROD_WEB_PORT }}
-      FRAME_FLOW_STORAGE_NAME: ${{ vars.FRAME_FLOW_STORAGE_NAME }}
-      PROD_STATE_VOLUME: ${{ vars.PROD_STATE_VOLUME }}
-      PROD_MOCK: ${{ vars.PROD_MOCK }}
-      PROD_WRITE_ENABLED: ${{ vars.PROD_WRITE_ENABLED }}
-      DOCKER_PIP_INDEX_URL: ${{ vars.DOCKER_PIP_INDEX_URL }}
-      DOCKER_PIP_FALLBACK_INDEX_URL: ${{ vars.DOCKER_PIP_FALLBACK_INDEX_URL }}
-      CI_PIP_INDEX_URL: ${{ vars.CI_PIP_INDEX_URL }}
-      CI_PIP_FALLBACK_INDEX_URL: ${{ vars.CI_PIP_FALLBACK_INDEX_URL }}
-      DEBIAN_MIRROR: ${{ vars.DEBIAN_MIRROR }}
-      DEBIAN_SECURITY_MIRROR: ${{ vars.DEBIAN_SECURITY_MIRROR }}
-    steps:
-      - uses: https://github.com/actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
-      - uses: https://github.com/actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
-        with:
-          python-version: '3.14'
-      - name: Install deploy tooling
-        run: python scripts/ci-install.py
-      - name: Plan or deploy production (default is plan)
-        env:
-          PRODUCTION_ENV: ${{ secrets.PRODUCTION_ENV }}
-        run: |
-          . ./deploy/build-cn.env
-          python scripts/production-deploy.py
-      - name: Recover interrupted production deployment
-        if: always()
-        env:
-          CD_ACTION: recover
-        run: |
-          if [ -n "${FRAME_FLOW_DEPLOY_OWNER:-}" ]; then
-            python scripts/production-deploy.py
-          fi
+# Production moved to Ubuntu Server. Release manually with scripts/server-release.py;
+# the shared NAS runner performs isolated verification only.

Dockerfile

@@ -1,5 +1,5 @@
 ARG PYTHON_BASE=python:3.14.5-slim-bookworm@sha256:ec58d916f9e24a6035cab2bdf07f6206c4cc092a16613c60597534711332d9d6
-FROM ${PYTHON_BASE}
+FROM ${PYTHON_BASE} AS prepared
 ARG DEBIAN_MIRROR=deb.debian.org
 ARG DEBIAN_SECURITY_MIRROR=deb.debian.org
 ARG TARGETARCH
@@ -37,6 +37,19 @@ RUN --mount=type=cache,id=frameflow-pip-py314-${TARGETARCH},target=/root/.cache/
     else python /build-tools/install.py --locked; fi
 COPY pigway_frame_flow ./pigway_frame_flow
 COPY vendor ./vendor
+# Publish only the cleaned filesystem, without retaining build-stage layers.
+RUN rm -rf /usr/local/lib/python*/site-packages/pip \
+      /usr/local/lib/python*/site-packages/pip-*.dist-info \
+      /usr/local/lib/python*/ensurepip \
+    && rm -f /usr/local/bin/pip /usr/local/bin/pip[0-9]* \
+    && find / -name .DS_Store -type f -delete
+
+FROM scratch
+COPY --from=prepared / /
+ENV PATH=/usr/local/bin:/usr/local/sbin:/usr/sbin:/usr/bin:/sbin:/bin LANG=C.UTF-8
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 TZ=Asia/Shanghai \
+    DATA_DIR=/data CONFIG_DIR=/config
+WORKDIR /app
 ARG BUILD_COMMIT=development
 ARG BUILD_TIME=unknown
 ENV BUILD_COMMIT=$BUILD_COMMIT BUILD_TIME=$BUILD_TIME

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Pigway
+Copyright (c) 2026 PIGWay
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

NOTICE.md

@@ -1,6 +1,6 @@
 # Notices
 
-Pigway Frame Flow is an independent project. KoKonna is a supported device
+PIGWay Frame Flow is an independent project. KoKonna is a supported device
 integration and is not affiliated with this project unless otherwise stated.
 KoKonna names and marks belong to their respective owners.
 

README.md

@@ -1,8 +1,8 @@
-# Pigway Frame Flow
+# PIGWay Frame Flow
 
 [简体中文](README.zh-CN.md) | English
 
-Pigway Frame Flow is a lightweight, self-hosted platform for programmable smart-frame automation. It runs independently on a NAS or server, with its own Web UI, image library, rendering, scheduler and REST API. KoKonna is a supported device integration; external applications do not need its credentials or SDK.
+PIGWay Frame Flow is a lightweight, self-hosted platform for programmable smart-frame automation. It runs independently on a NAS or server, with its own Web UI, image library, rendering, scheduler and REST API. KoKonna is a supported device integration; external applications do not need its credentials or SDK.
 
 ### Installation
 
@@ -37,6 +37,8 @@ python3.14 -m venv .venv
 
 The demo forces mock mode and disables device writes. Data and configuration remain in `data/` and `config/` across restarts.
 
+Synology Photos API sources work without `/photos` or NFS mounts, with shared/current-account personal spaces, people filters and bounded on-demand XL preview caching. Original downloads are not supported by this verified implementation. See [Photos API and Ubuntu migration candidate](docs/SYNOLOGY_PHOTOS_API.md).
+
 ### Features and boundaries
 
 - Chinese and English Web UI, light/dark themes, account login, device dashboard and image previews.
@@ -45,7 +47,7 @@ The demo forces mock mode and disables device writes. Data and configuration rem
 - Seven templates: Daily Dashboard, Weather, Calendar, Quote, Photo + Text, Daily Poetry and System Alert.
 - Layout Studio for collages/posters with 1–12 images; optional OpenAI-compatible layout planning and source-driven automatic collages.
 - Device-bound schedules, ordered/random playlists, temporary priority overrides, restore and persistent operation history.
-- Read-only NAS folders, Synology Photos person filtering, WebDAV and optional cloud-drive connectors. Each source has its own configuration and authorization.
+- Read-only NAS folders, Synology Photos person filtering, WebDAV and optional cloud-drive connectors. Each source has its own folder and filter settings. People filtering uses one shared Synology Photos sign-in; WebDAV and cloud-drive credentials belong to their respective sources.
 - Optional weather, calendar, monitoring, AI, MQTT and webhook integrations. Provider configuration is required; an unconnected provider is not a working connection.
 
 Templates **render images**, including text-only templates. Choose a template, edit its data, generate a preview, then display it. Preview generation and saving template settings do not update the frame. Photo + Text and Daily Dashboard can include a selected local photo; other templates do not automatically choose one. Scheduled template jobs render afresh on each run. See [photo sources](docs/PHOTO_SOURCES.md), [automatic collages](docs/AUTOMATIC_COLLAGE.md) and [integration setup/limits](docs/EXTENSIONS.md).

README.zh-CN.md

@@ -1,4 +1,4 @@
-# Pigway Frame Flow
+# PIGWay Frame Flow
 
 简体中文 | [English](README.md)
 
@@ -37,10 +37,12 @@ python3.14 -m venv .venv
 
 演示强制使用 Mock，并关闭设备写入。数据与配置保存在 `data/`、`config/`，重启后保留。
 
+Synology Photos 可使用独立的 API 来源，无需 `/photos` 或 NFS 挂载；支持共享 / 当前账号个人空间、人物筛选和按需 XL 预览缓存。原图下载不在本次已验证支持范围内。见 [API 来源与 Ubuntu 候选迁移说明](docs/SYNOLOGY_PHOTOS_API.md)。
+
 ### 功能与边界
 
 - 中英文 Web 界面、深浅色主题、账号登录、设备面板与图片预览。
-- 本地暂存和 KoKonna 云端图库，上传、切换、星标、来源/任务筛选及批量操作。
+- NAS 本地图库和 KoKonna 云端图库；星标、来源/任务筛选及批量操作位于本地图库，上传到云端并显示需单独操作。
 - 保持比例的 contain/cover/smart 图片转换，彩色/灰度模式与照片数据源的横竖方向选择。
 - 七种模板：家庭早报、天气、日历、一句话、照片与文字、每日诗词、系统告警。
 - 拼图工作室支持 1–12 张图片的拼图与海报；可选 OpenAI 兼容接口排版，以及从数据源自动选图拼接。
@@ -67,6 +69,8 @@ Web UI / Scheduler / REST API → DisplayService → FrameDeviceDriver → KoKon
 
 Ticktar 集成为可选项，Frame Flow 不依赖 Ticktar 启动，也不访问其数据库。参见[外部集成契约](docs/integrations/TICKTAR.md)。
 
+Console 监控接入提供独立只读 ZIP 插件，支持服务就绪、画框在线/电量及任务最近结果，见 [Console 插件安装说明](../pigway-console-adapter-frame-flow/README.md)。
+
 ### 存储与安全
 
 Docker 持久化 `/data/frameflow.db`、`/data` 下的图片/生成文件/缓存，以及 `/config` 下的私有配置和会话文件。容器以 UID/GID 10333 运行，根文件系统只读，使用独立桥接网络、`unless-stopped` 重启策略和有大小限制的标准输出日志；不需要 privileged、host network 或 Docker socket。

deploy/Dockerfile.runtime-update

@@ -0,0 +1,32 @@
+# Reuse a reviewed image only when the locked Python dependencies are identical.
+# For a fresh installation use the repository's main Dockerfile instead.
+ARG BASE_IMAGE
+FROM ${BASE_IMAGE} AS prepared
+# Cleanup runs only in the disposable preparation stage.
+USER 0
+COPY requirements.lock /app/requirements.expected.lock
+RUN python -c "from pathlib import Path; assert Path('/app/requirements.lock').read_bytes() == Path('/app/requirements.expected.lock').read_bytes(), 'Dependency lock changed; use the full Dockerfile'"
+COPY pigway_frame_flow /app/pigway_frame_flow
+COPY vendor /app/vendor
+# Publish only the cleaned filesystem, without retaining build-stage layers.
+RUN rm -rf /usr/local/lib/python*/site-packages/pip \
+      /usr/local/lib/python*/site-packages/pip-*.dist-info \
+      /usr/local/lib/python*/ensurepip \
+    && rm -f /usr/local/bin/pip /usr/local/bin/pip[0-9]* \
+    && find / -name .DS_Store -type f -delete
+
+FROM scratch
+COPY --from=prepared / /
+ENV PATH=/usr/local/bin:/usr/local/sbin:/usr/sbin:/usr/bin:/sbin:/bin LANG=C.UTF-8
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 TZ=Asia/Shanghai \
+    DATA_DIR=/data CONFIG_DIR=/config
+WORKDIR /app
+USER 10333:10333
+EXPOSE 18787
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:18787/health',timeout=3)"
+CMD ["python", "-m", "uvicorn", "pigway_frame_flow.main:app", "--host", "0.0.0.0", "--port", "18787", "--workers", "1", "--no-access-log"]
+ARG BUILD_COMMIT
+ARG BUILD_TIME
+ENV BUILD_COMMIT=$BUILD_COMMIT BUILD_TIME=$BUILD_TIME
+LABEL org.opencontainers.image.title="PIGWay Frame Flow" org.opencontainers.image.version="0.1.17" org.opencontainers.image.revision=$BUILD_COMMIT

deploy/compose.ubuntu-photos-api.yml

@@ -0,0 +1,51 @@
+# Candidate only. Never start alongside a live-writing NAS instance.
+name: pigway-frame-flow
+services:
+  pigway-frame-flow:
+    image: ${FRAME_FLOW_IMAGE:?Set the verified immutable image reference}
+    container_name: pigway-frame-flow
+    platform: linux/amd64
+    restart: unless-stopped
+    init: true
+    user: "10333:10333"
+    ports:
+      - "${FRAME_FLOW_BIND:-192.0.2.10}:81:18787"
+    env_file: ${FRAME_FLOW_ENV_FILE:-/srv/pigway/apps/pigway-frame-flow/.env}
+    environment:
+      TZ: Asia/Shanghai
+      DATA_DIR: /data
+      CONFIG_DIR: /config
+      FRAME_FLOW_STORAGE_NAME: Ubuntu Server
+      SYNOLOGY_PHOTOS_CACHE_BYTES: ${SYNOLOGY_PHOTOS_CACHE_BYTES:-268435456}
+      # Migration starts read-only. Activation is a separate authorized action.
+      KOKONNA_WRITE_ENABLED: "false"
+      PYTHONDONTWRITEBYTECODE: "1"
+      TMPDIR: /data/tmp
+    volumes:
+      - type: bind
+        source: /srv/pigway/apps/pigway-frame-flow/data
+        target: /data
+        bind:
+          create_host_path: false
+      - type: bind
+        source: /srv/pigway/apps/pigway-frame-flow/config
+        target: /config
+        bind:
+          create_host_path: false
+    read_only: true
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    pids_limit: 100
+    mem_limit: 768m
+    healthcheck:
+      test: [CMD, python, -c, "import urllib.request; urllib.request.urlopen('http://127.0.0.1:18787/ready',timeout=3)"]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+    # Docker data-root and container logs must reside on the T7 too.
+    logging:
+      driver: json-file
+      options:
+        max-size: 10m
+        max-file: "3"

deploy/docker-compose.photos.yml

@@ -1,14 +1,6 @@
-# Opt-in read-only photo mount. Set NAS_PHOTOS_DIR to the actual NAS folder.
+# Retired: filesystem photo mounts are forbidden. Use Photos API sources.
+# This compatibility filename intentionally grants no additional host access.
 services:
   pigway-frame-flow:
     environment:
-      PHOTO_ROOT: /photos
-    group_add:
-      - "${NAS_PHOTOS_GID:-10333}"
-    volumes:
-      - type: bind
-        source: ${NAS_PHOTOS_DIR:?Set NAS_PHOTOS_DIR to your existing photo directory}
-        target: /photos
-        read_only: true
-        bind:
-          create_host_path: false
+      SYNOLOGY_PHOTOS_CACHE_BYTES: ${SYNOLOGY_PHOTOS_CACHE_BYTES:-268435456}

docs/PHOTO_SOURCES.md

@@ -4,6 +4,10 @@ Photo sources are independent read-only providers. They never call a frame drive
 SQLite persists source definitions and Scheduler jobs; passwords are not stored there.
 The shared DisplayService handles fitting, upload, idempotency, overrides and restore.
 
+## Synology Photos API (no mount)
+
+Use the explicit `synology-photos` source type for Ubuntu without `/photos`. Existing local sources are not silently converted. Shared and current-account personal spaces use the shared Photos login, with ID-based any/all people filters and bounded XL preview caching. See [verified capabilities, migration and recovery](SYNOLOGY_PHOTOS_API.md). Original API downloads remain unsupported.
+
 ## NAS local folder
 
 Add the actual existing photo directory to `.env`:
@@ -30,7 +34,7 @@ change NAS permissions. Unreadable roots return an explicit HTTP 403 rather than
 an empty catalog.
 Missing host folders fail explicitly rather than being created automatically.
 
-Open **Gallery → Photo sources → Add source**, choose **NAS local folder**,
+Open **Photo sources → Add source**, choose **NAS local folder**,
 enter a relative folder (`.` for root or `family` for a subfolder).
 Supported formats: JPEG, PNG, WebP. Optional recursion excludes hidden directories,
 Synology `@eaDir` thumbnail trees, and symlinks. Original files remain unchanged.
@@ -134,7 +138,7 @@ caption still comes from the original curated directory.
 
 1. 将共享图库（如 `/volume1/photo`）挂载为 `/photos`，保持只读。
 2. 在 `.env` 配置 `SYNOLOGY_PHOTOS_URL=https://NAS_IP:9115` 和 `SYNOLOGY_PHOTOS_CERT_SHA256`（服务实际 TLS 证书的 SHA-256 指纹，从可信 NAS 配置核实）。重建容器后生效。指纹变化时必须重新核实；每次连接在发送登录信息前校验同一个 TLS socket 的证书。
-3. 照片数据源 → 编辑数据源 → 连接 / 选择人物。管理员输入 NAS 用户名、密码；只保存 session 到 `/config/synology-photos-session.json`（0600），不保存密码。会话过期后需要重新连接；断开连接删除本地 session。页面没有 password/token 回显。
+3. 照片数据源 → 顶部共享连接 → 连接 Synology Photos。输入有权限的 NAS 用户名、密码；只保存 session 到 `/config/synology-photos-session.json`（0600），不保存密码。会话过期后需要重新连接；断开连接删除本地 session。页面没有 password/token 回显。登录由所有人物筛选数据源共享；随后进入各数据源编辑器选择人物。
 4. 选择人物，启用筛选，选择“任意”或“同时包含所有”。默认只列出已命名人物，可搜索 ID、展开未命名分组。至少选择一个人物。
 5. 与当前本地目录、日期文件夹规则取交集，再随机选图。原文件夹标题、日期、地点仍保留。不匹配返回空图库；预览 / 定时任务失败，不回退到全图库。
 

docs/REAL_DEVICE_TEST.md

@@ -9,7 +9,7 @@
    duplicates, name/date/dimensions anomalies. No download-all action.
 3. Stop on discrepancy. Missing model fields must be reported as unavailable.
 4. Once explicitly authorized, locally render **one** 1200×1600 test image containing
-   PIGWAY FRAME FLOW TEST and Shanghai timestamp, no private content.
+   PIGWay Frame Flow TEST and Shanghai timestamp, no private content.
 5. Record an operation ID and previous image; one upload only, no write retries.
 6. Poll device read-only no more often than 60 seconds, respecting the 20/min budget.
    Confirm imageId and synced. If sent but response lost, mark UNKNOWN, block writes,

docs/SYNOLOGY_PHOTOS_API.md

@@ -0,0 +1,65 @@
+# Synology Photos API 来源与 Ubuntu 迁移候选
+
+本功能从 NAS 的 Photos API 按需读取照片，不需要 NFS、SMB 或 `/photos` 文件挂载。NAS 原照片不复制整库到 Server。
+
+## 已支持与边界
+
+- 新来源类型 `synology-photos`，与 `local` 挂载目录明确分开。
+- 共享空间 `SYNO.FotoTeam`、当前登录账号的个人空间 `SYNO.Foto`；不是任意 NAS 用户的个人空间。
+- 人物列表分批读取，照片按 ID 做 any 并集 / all 交集；无匹配时明确为空，不回退全库。
+- 支持目录相对路径、递归开关、日期文件夹 / 标题、方向及现有质量筛选。`.` 表示所选空间根目录；路径以 Photos 返回的目录名为准，不是 Ubuntu 绝对路径。
+- 图片使用经过实测的 `Thumbnail.get` v2、`size=xl`。原始文件名不代表下载的是原图。对 NAS 当前原图下载接口的探测被拒绝，原图下载**未宣称支持**。
+- 照片枚举 `Browse.Item.list` v7，人物 `Browse.Person.list` v3；每批 500 条，最多 100000 条，超过明确失败，界面目录上限仍由 `catalog_limit` 控制。不支持 NAS 未暴露或账号无权访问的相册。
+- 旧 `local` 来源保留挂载读取方式，不自动变成 API 来源。新建 / 编辑来源时可明确选择 API 类型。
+
+## 安全与缓存
+
+保持 HTTPS SHA-256 证书指纹校验，在同一 TLS socket 验证证书后才发送 SID。仅调用固定 API 与只读方法，不使用通用 RPC 转发、不跟随重定向。密码不持久化，会话文件保持 0600。会话过期返回明确重连提示；不保存密码以自动重登，也不对 NAS 原会话发 logout。权限不足与会话失效分开处理。
+
+缓存为 `/data/cache/synology-photos`，默认总图片字节上限 256 MiB，可用 `SYNOLOGY_PHOTOS_CACHE_BYTES` 调整（环境配置最小 1 MiB），单张不超过应用 20 MiB 限制。只下载选中的图片。文件锁合并跨线程、跨进程下载，预留容量后写 0600 临时文件，完成长度核对及 Pillow 验证 / 解码后原子提交；超时、中断及无效数据清理临时文件，下次持锁读取清理进程异常退出遗留的 `.part`。按最近使用淘汰。缓存身份包含端点、会话摘要、空间、照片 ID、索引版本及缩略图缓存键，避免账号 / 空间混用。
+
+容量上限针对图片和下载临时文件的逻辑字节，不含 SQLite、锁文件与文件系统元数据；并发串行缓存锁会等待正在进行的单张下载。网络 socket 超时 30 秒，流读取检查 90 秒期限，已阻塞的单次 socket 读取最多再等待其超时。
+
+## Ubuntu 候选配置
+
+正式代码在 `/home/developer/Documents/Projects/pigway-frame-flow` 的 `codex/synology-photos-api` 分支开发，不能以迁移临时解包目录作为开发仓库。
+
+候选文件：`deploy/compose.ubuntu-photos-api.yml`。外部 `192.0.2.10:81`，内部 `18787`，UID/GID `10333:10333`，数据和配置固定为：
+
+- `/srv/pigway/apps/pigway-frame-flow/data:/data`
+- `/srv/pigway/apps/pigway-frame-flow/config:/config`
+
+无 `/photos` 绑定。`create_host_path: false` 防止在 T7 未挂载时悄悄创建目录；但仍需在启动前检查 `findmnt -T /srv/pigway` 的实际源设备。
+
+`.env` 需从已确认的配置安全迁移，保留 Photos URL、证书 pin 与已有 Frame Flow / 相框鉴权；不要把密钥写入仓库。模板默认 `KOKONNA_WRITE_ENABLED=false`。创建 `data/tmp`，属主保持 10333:10333，`TMPDIR=/data/tmp`。Docker data-root 和 containerd root 也必须在 T7，不能仅检查 bind mount。
+
+```sh
+# 仅检查候选配置；不会启动应用。
+FRAME_FLOW_IMAGE='<已验证的镜像标签>' docker compose -f deploy/compose.ubuntu-photos-api.yml config --quiet
+```
+
+完整构建使用根目录 Dockerfile。若使用 `deploy/Dockerfile.runtime-update`，必须指定已审核的基础镜像，构建步骤会检查依赖锁与基础镜像相同；不相同时必须完整构建。本次依赖未新增，已比对现有 0.1.8 基础镜像的锁文件。
+
+## 旧来源转换与恢复
+
+**停止目标实例、复制数据、转换真实配置及切换部署均需另行授权，本次没有执行。**
+
+1. 确认 T7 挂载，备份 NAS 原有完整 `/data`、`/config`、旧镜像及 Compose。SQLite 必须停服务后复制，或使用 SQLite backup API；不要只复制有活动 WAL 的主文件。
+2. 将备份恢复到上述 Server 目录，保持私密文件权限，创建 `data/tmp`。保留旧 NAS 备份直至切换验收。
+3. 对每个需要摆脱挂载的来源显式 dry run：
+
+   ```sh
+   python scripts/migrate-photos-api.py --database /data/frameflow.db --source family
+   # 已获授权、目标服务已停止时才执行：
+   python scripts/migrate-photos-api.py --database /data/frameflow.db --source family --apply --service-stopped
+   ```
+
+   工具保持来源 ID、任务引用、人物空间、any/all、目录、方向及筛选设置，只修改来源类型并关闭旧本地 `@eaDir` 预览开关；自动在同一数据目录生成 0600 SQLite 备份。转换不会验证该账号在 Photos 中是否可访问相同目录，必须再做真实只读预览。不要转换确实依赖挂载且 Photos 未收录的目录。
+4. 已获得单独授权后才停旧实例、以只读候选配置启动 Server，并逐个来源验收。没有授权前不执行 `compose up` 或开启真实写入。
+5. 回退时停止 Server，恢复已备份的数据库和配置（停服务时处理对应 WAL/SHM），恢复旧来源类型与 NAS 原部署，保证只有一个实例有写权限。原 NAS 照片不受缓存或来源转换影响。
+
+## NFS 授权判断
+
+API 来源的共享 / 个人空间取图已经可以完全不依赖 NFS，因此这条新取图链路不需要为 `192.0.2.10` 保留 DSM `photo` NFS 授权。但目前旧来源和待迁移配置没有全部切换验收，不能据此宣称迁移完成或旧本地来源已可脱离挂载。确认没有其他已批准用途后，可以单独授权删除该特定 NFS 规则；本次没有删除。
+
+实际版本、镜像标识、通过 / 失败 / 未执行项见本任务验证记录。

docs/UI_LAYOUT_AUDIT.md

@@ -39,7 +39,7 @@ FRAME_FLOW_SCREENSHOT_DIR 可选，用于保存仅含测试数据的截图。
 | --- | --- | --- |
 | ui-layout-audit.cjs | 11 页面、本地/云端图库、6 类弹窗、展开手动拼版；溢出、控件间距、触控高度、弹窗边界 | 16 组尺寸/语言/主题组合，305 项通过 |
 | ui-image-loading.cjs | 三种宽度、明暗主题；局部居中、成功解码、错误提示与无障碍状态 | 45 项通过 |
-| ui-progressive-loading.cjs | 阻塞初始化/元数据/图片/任务筛选；真实图片数量、搜索先于图片请求、无骨架 | 14 项通过 |
+| ui-progressive-loading.cjs | 阻塞初始化/元数据/图片/任务筛选；首次无缓存时控件先就绪、输入保留、慢请求切换、列表失败、无骨架 | 18 项通过 |
 | ui-studio-image-loading.cjs | 桌面/手机、明暗主题；并行请求、独立完成/失败、坐标与拖动、稳定区域 | 31 项通过 |
 
 上述检查无页面脚本异常。生产静态文件与构建文件哈希比对、health/ready 检查通过；
@@ -47,3 +47,16 @@ FRAME_FLOW_SCREENSHOT_DIR 可选，用于保存仅含测试数据的截图。
 不代表真实账号密码登录、AI 生成、iOS/Android 实机或软键盘测试。
 
 连接中心内容较长，后续可按用户任务分组；模板与排版导航图标仍有重复。
+
+
+## 首次未缓存图库的初始化
+
+目的地标签、搜索、排序、刷新和上传控件必须先于列表接口完成。
+仅已有列表的缓存分支先渲染还不够；无缓存时也应创建真实控件与空的列表容器。
+元数据返回前不推测图片数量，不显示真实空图库提示，不生成骨架卡片。
+列表失败保留页面控件；慢云端请求期间切换 NAS，迟到响应不得覆盖新页面。
+列表返回后保留之前输入的搜索词和排序。任务筛选在同一导航内复用请求，仍不阻塞图库。
+
+启动使用 Settings API 中不调用厂商接口的 device_catalog；完整设备状态作为后台更新，
+迟到响应在退出账号后不应用。ui-gallery-bootstrap.cjs 同时阻塞设备状态与图片列表，
+验证真实控件仍先显示，列表返回后保留查询和排序，2 项通过。

docs/audits/2026-10-16-ui-copy.md

@@ -0,0 +1,27 @@
+# 界面表达审计（2026-10-16）
+
+范围：11 个主页面、主要弹窗、中英文文案、README 和照片数据源说明；对照当前 API、清理与来源记录逻辑。不是厂商接口能力或线上服务状态的全面审计。
+
+| 位置 | 原问题 | 修正 |
+| --- | --- | --- |
+| 图库 | 排序使用“适配方式” | 独立“排序方式”标签 |
+| 轮播 / 播放列表 | 播放顺序使用图片适配标签；间隔重复单位 | 使用“播放顺序”“切换间隔” |
+| 总览 | 天气缺译，显示原始 weather | 补齐中英文 |
+| 总览 | 图片 ID 标成图片；型号来源标成型号 | 独立标注 ID 与信息来源 |
+| 同步状态 | “已同步”容易被视为实物刷新确认 | 标明云端确认 |
+| 图片来源 | 无记录却断言非本系统生成 | 只描述未找到可用记录 |
+| 模板编辑 | 非模板图片复用不准确的来源错误 | 明确无可编辑的模板来源 |
+| 删除 | 本地当前图也提示画框切图 | 按本地、云端、当前云端副本区分确认文案 |
+| 星标 / 多选 | 自动清理保护及隐藏勾选项范围不明确 | 加入服务端保留、手动删除、当前页选择范围说明 |
+| 上传 | 固定尺寸提示可能与输出不一致 | 提示以生成预览为准 |
+| 显示选项 | 不勾选恢复时仍显示时长，容易误解 | 说明时长与优先级的临时显示用途 |
+| 数据源 | 未配置与无匹配照片共用空态 | 拆分两种空态 |
+| 数据源 | 位置标签、凭据提示仅描述 WebDAV | 补充网盘目录 ID、百度路径、OAuth 凭据 |
+| 人物筛选 | 仅描述共享空间，但实际可选个人空间 | 按所选空间说明访问权限 |
+| AI / MQTT | AI 密钥称为设备密钥；连接状态缺译 | 独立 API 密钥标签，补齐连接状态 |
+| 错误页 | 所有失败都归因设备云端 | 改成通用页面加载失败，保留具体原因 |
+| 文档 | 照片数据源旧入口及账号独立性描述过时 | 对齐独立导航与共享 Photos 登录 |
+
+验证：305 项布局检查覆盖 320、390、844 横屏、1440 宽度，中英文与明暗主题，11 页及主要弹窗；8 组星标 / 反选回归；新增文案检查覆盖静态翻译完整性、排序 / 播放 / 型号标签、本地删除和星标作用范围。测试使用隔离 Mock，无真实设备写入、照片删除、AI 调用或部署。
+
+此前未提交的反选、总览图片放大及共享图片查看器改动保留。此报告不代表已提交或已部署。

docs/openapi.json

@@ -1,8 +1,8 @@
 {
   "openapi": "3.1.0",
   "info": {
-    "title": "Pigway Frame Flow API",
-    "version": "0.1.6"
+    "title": "PIGWay Frame Flow API",
+    "version": "0.1.9"
   },
   "paths": {
     "/api/v1/devices/{device_id}/widgets/selection": {
@@ -14203,6 +14203,17 @@
       },
       "Asset": {
         "properties": {
+          "source_path": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Source Path"
+          },
           "starred": {
             "type": "boolean",
             "title": "Starred",
@@ -14819,6 +14830,24 @@
         ],
         "title": "Device"
       },
+      "DeviceIdentity": {
+        "properties": {
+          "id": {
+            "type": "string",
+            "title": "Id"
+          },
+          "name": {
+            "type": "string",
+            "title": "Name"
+          }
+        },
+        "type": "object",
+        "required": [
+          "id",
+          "name"
+        ],
+        "title": "DeviceIdentity"
+      },
       "DisplayGeometry": {
         "properties": {
           "width": {
@@ -15198,7 +15227,7 @@
           "version": {
             "type": "string",
             "title": "Version",
-            "default": "0.1.6"
+            "default": "0.1.9"
           }
         },
         "type": "object",
@@ -16209,6 +16238,17 @@
             ],
             "title": "Caption"
           },
+          "source_path": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Source Path"
+          },
           "provider_preview": {
             "type": "boolean",
             "title": "Provider Preview",
@@ -16314,6 +16354,7 @@
             "type": "string",
             "enum": [
               "local",
+              "synology-photos",
               "webdav",
               "google-drive",
               "alipan",
@@ -16327,6 +16368,19 @@
             "minLength": 1,
             "title": "Location"
           },
+          "nas_root_path": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 2048,
+                "pattern": "^/"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Nas Root Path"
+          },
           "recursive": {
             "type": "boolean",
             "title": "Recursive",
@@ -16375,6 +16429,20 @@
             ],
             "title": "Orientation"
           },
+          "minimum_short_edge": {
+            "type": "integer",
+            "maximum": 50000.0,
+            "minimum": 0.0,
+            "title": "Minimum Short Edge",
+            "default": 0
+          },
+          "minimum_long_edge": {
+            "type": "integer",
+            "maximum": 50000.0,
+            "minimum": 0.0,
+            "title": "Minimum Long Edge",
+            "default": 0
+          },
           "minimum_sharpness": {
             "type": "number",
             "maximum": 10000.0,
@@ -16466,6 +16534,7 @@
             "type": "string",
             "enum": [
               "local",
+              "synology-photos",
               "webdav",
               "google-drive",
               "alipan",
@@ -16479,6 +16548,19 @@
             "minLength": 1,
             "title": "Location"
           },
+          "nas_root_path": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 2048,
+                "pattern": "^/"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Nas Root Path"
+          },
           "recursive": {
             "type": "boolean",
             "title": "Recursive",
@@ -16527,6 +16609,20 @@
             ],
             "title": "Orientation"
           },
+          "minimum_short_edge": {
+            "type": "integer",
+            "maximum": 50000.0,
+            "minimum": 0.0,
+            "title": "Minimum Short Edge",
+            "default": 0
+          },
+          "minimum_long_edge": {
+            "type": "integer",
+            "maximum": 50000.0,
+            "minimum": 0.0,
+            "title": "Minimum Long Edge",
+            "default": 0
+          },
           "minimum_sharpness": {
             "type": "number",
             "maximum": 10000.0,
@@ -17145,6 +17241,13 @@
             "type": "array",
             "title": "Gallery Destinations"
           },
+          "device_catalog": {
+            "items": {
+              "$ref": "#/components/schemas/DeviceIdentity"
+            },
+            "type": "array",
+            "title": "Device Catalog"
+          },
           "version": {
             "type": "string",
             "title": "Version"
@@ -17382,12 +17485,12 @@
           "product": {
             "type": "string",
             "title": "Product",
-            "default": "Pigway Frame Flow"
+            "default": "PIGWay Frame Flow"
           },
           "version": {
             "type": "string",
             "title": "Version",
-            "default": "0.1.6"
+            "default": "0.1.9"
           },
           "api_version": {
             "type": "string",

docs/releases/v0.1.11.md

@@ -0,0 +1,7 @@
+# v0.1.11
+
+照片底部单行按“日期 · 已命名人物 · 主题 · 地点 · 文件名”排列，空项省略，人物之间也使用 ` · `。主题、日期和地点沿用最近的日期文件夹解析；没有结构化日期目录时仍保留文件名。人物来自 Synology Photos 已命名人物相册的实际图片归属，按账号会话和空间缓存 15 分钟，不显示未命名人物编号。人物查询失败时保留图片及其他描述。
+
+新建照片源默认开启底部文字，既有来源保留明确设置。横向来源继续同时约束选图和生成画布，不拉伸图片。更新来源表单说明与浏览描述顺序。
+
+使用既有 Ubuntu Server 发布流程，备份配置、数据库与 Compose，从提交源码构建并核验部署哈希；失败恢复旧 Compose。发布过程不主动切换真实画框，不重绘历史图库图片。

docs/releases/v0.1.12.md

@@ -0,0 +1,5 @@
+# v0.1.12
+
+修复临时展示到期或手动恢复后，“上一张图片”仍指向当前图片，导致已确认删除仍被恢复保护拦截的问题。只有设备已确认同步到受管理的当前图片、且没有基础恢复目标、临时展示或待确认写入时，才清除这条自身引用；不同图片的有效恢复引用继续受保护。既有残留引用在读取设备状态或删除校验时自动修正，不需要强制删除图片或重置数据库。
+
+有效恢复引用仍拒绝删除，并通过结构化原因显示中英文提示。保留当前图片删除确认，不主动删除照片或切换画框。

docs/releases/v0.1.13.md

@@ -0,0 +1,3 @@
+# v0.1.13
+
+照片底部同时显示所有已识别且已命名的人物，人物之间使用 ` & `；日期、人物、主题、地点及文件名之间继续使用 ` · `。例如 `2026-10-18 · Alice & Bob · Family · one.jpg`。人物仍来自 Photos 实际相册归属，未命名人物不显示；历史生成图片不自动重绘。

docs/releases/v0.1.14.md

@@ -0,0 +1,5 @@
+# v0.1.14
+
+底部文字仅显示日期、已命名人物（使用 & 连接）、文件夹主题及地点，不显示原始文件名。原始文件名仍用于图库和诊断记录。
+
+上传传输区分明确的 DNS/连接建立失败与已建立连接中断：前者尚未发送 HTTP 写入，最多重试三次，失败后结束该次操作，不进入阻塞后续写入的 UNKNOWN；读超时或连接中断等不确定结果继续保留核对保护，不盲目重放上传。既有未知操作通过只读设备/图库核验后使用原有 acknowledge 流程关闭，保留原始错误和审计记录。

docs/releases/v0.1.15.md

@@ -0,0 +1,9 @@
+# v0.1.15
+
+自动照片、拼版、模板及数据模板任务在上传失败后，持久保存同一张暂存图片，并在下一次计划之前安排最多 5 次额外重试。间隔按 1、2、4、8、16 权重递增，随剩余窗口缩放，计划时间集中在窗口前半段，为上传与设备同步留出时间。重试不移动原定计划，也不复用旧操作 ID；每次独立记录操作及事件。成功后取消剩余重试，重启后沿用已有计数与截止时间；停用任务不再追加重试，删除任务取消其重试计划。
+
+若额外重试均失败，下一次计划仍先上传同一张图；若这一次仍失败，只删除该任务未入库、未星标的生成缓存，再按照片源生成并上传新图。NAS 原照片、用户上传文件和成功图库图片不由此流程删除。新图仍失败时，进入它自己的下一轮恢复窗口。
+
+上传结果未知不再阻塞后续独立上传。每次重试前先只读核对设备及云图库，精确确认已成功的上传不再重传；需继续尝试时关闭旧尝试并保留错误和核对审计。删除、恢复及自动清理仍保留各自的保护条件。重试窗口到期后不再启动额外上传，待同步尝试经核对结束后交给原计划执行。
+
+任务生成图片先保存在缓存，确认任务成功后才进入本地图库；失败不会产生看似成功的本地图库记录。额外重试仍归属原任务的云端保留规则，任务列表显示最近尝试结果。

docs/releases/v0.1.16.md

@@ -0,0 +1,12 @@
+# v0.1.16
+
+统一 PIGWay 品牌写法，优化图库、自动化、历史记录、设置、连接中心和拼图页面布局。
+
+- 图库直接点击图片查看，移除重复的查看按钮；缩略图底框为正方形，卡片宽度适配单行操作按钮。
+- 全站共用更宽的内容区域，宽屏图库可一行显示三张卡片；搜索、排序、来源和任务筛选合并排列。
+- 自动化与历史记录状态改为仅保留颜色的文字，优化列宽与操作对齐。
+- 设置与鉴权信息保持左右并排，鉴权卡片内部信息改为单列；相关设置控件紧凑排列。
+- 连接中心和自动拼图短字段合并排列，按钮按内容宽度显示，空结果提示不再占据额外空间。
+- 窄屏自动换行，保留图片预览、长文本和表格所需空间。
+
+本轮界面检查覆盖 11 个主页面、本地图库及弹窗，中英文、明暗主题和四种屏幕宽度共 289 项布局检查通过；隔离环境拼图流程 8 项检查通过。生产部署后的界面复查使用隔离数据，没有执行真实画框写入。

docs/releases/v0.1.17.md

@@ -0,0 +1,11 @@
+# v0.1.17
+
+- 总览预览改用原图，避免放大低分辨率缩略图。
+- 云端图库缩略图升级为最大 860×860，等比缩放、JPEG 质量 88；原位替换旧缓存，仍只保留一档。点击放大继续读取原图。
+- 照片源新增最小短边、最小长边参数，同时检查源照片和实际取得的预览尺寸，默认 0 不限制。
+- 本地图库显示 NAS 原照片完整路径并支持换行，保留原文件名大小写和后缀；历史四张图片已按照片 ID 核实并补齐来源。
+- 自动化新增“目标相框”列；历史记录的状态、结果、调用方及操作按钮垂直居中。
+- 左上角统一显示 PIGWay Frame Flow，移除图标和重复品牌前缀。
+- 设置与鉴权保持左右并排、卡片等高，鉴权内部单列。图片预览弹窗保留原有布局。
+
+不修改 NAS 原照片，不主动切换真实画框。清理仅针对项目临时构建物及过期镜像，保留持久数据和近期回滚资源。

docs/releases/v0.1.5.md

@@ -1,4 +1,4 @@
-# Pigway Frame Flow v0.1.5
+# PIGWay Frame Flow v0.1.5
 
 ## 简体中文
 

docs/releases/v0.1.6.md

@@ -1,4 +1,4 @@
-# Pigway Frame Flow v0.1.6
+# PIGWay Frame Flow v0.1.6
 
 ## 简体中文
 

docs/releases/v0.1.7.md

@@ -0,0 +1,24 @@
+# PIGWay Frame Flow v0.1.7
+
+## 简体中文
+
+修复首次打开图库时内容区空白、必须等待云端图片列表返回才出现控件的问题。
+
+- 目的地标签、搜索、排序、刷新和上传按钮立即初始化，图片列表独立请求。
+- 仅在工具栏提示正在读取列表；未知数量时不生成图片卡片，不提前显示“图库为空”。实际图片仍在自己的区域内独立加载。
+- 启动使用轻量设备身份目录，完整设备状态在后台更新，避免厂商状态请求阻塞首屏。
+- 慢请求期间可以切换到 NAS 图库；过期响应不会覆盖当前页面。
+- 列表失败时保留控件并在工具栏显示错误，仍可刷新或切换目的地。
+- 保留等待期间输入的搜索词和排序选择；本地任务筛选请求在同一次导航内复用。
+
+### 验证
+
+本地 508 项 Python 测试、Ruff、格式检查、mypy 和 JavaScript 语法检查通过。
+新增首次未缓存列表的控件就绪、输入保留、慢云端切换和列表失败回归。
+不增加图库列表的服务端缓存，不修改厂商请求重试、照片、生成内容或设备写入策略。
+
+## English
+
+Fix the blank gallery on its first uncached visit. Destination tabs and gallery controls initialize before metadata requests complete.
+Slow or failed cloud listing does not prevent switching to NAS storage. Search and sort choices survive list arrival, and stale responses cannot replace the active destination.
+Only a small toolbar status indicates metadata loading; real images keep independent loading indicators.

docs/releases/v0.1.8.md

@@ -0,0 +1,13 @@
+# PIGWay Frame Flow v0.1.8
+
+增加 NAS 本地图库反选、放大总览图片，并统一图片查看器与界面表达。
+
+- 反选只切换当前页可见图片的勾选状态；隐藏勾选项的批量操作范围明确提示。
+- 总览当前图片预览增大，点击或键盘打开与图库相同的查看器，读取原图并支持适应屏幕、原始尺寸和 Esc 关闭。
+- 修正图库排序、播放顺序、型号信息来源、云端确认状态等标签，补齐天气与连接状态翻译。
+- 区分本地与云端删除影响，解释星标保留规则，避免对未知来源作无依据判断。
+- 修正数据源空态、路径与凭据说明；同步 README 和操作文档中的共享 Photos 登录机制与入口。
+
+验证：305 项布局检查、8 组星标与反选检查、12 组总览查看器检查、45 项图片加载检查及新增中英文文案检查通过。全套后端与静态检查由本次发布流水线再次验证。检查不涉及真实照片删除、设备写入或收费 AI 调用。
+
+Improve NAS gallery selection, dashboard image viewing and UI wording. Invert selection affects visible items on the current page. Dashboard previews open the same full-image viewer as the gallery. Storage destinations, deletion scope, server-side stars, cloud confirmation and shared Photos credentials are clarified in both languages.

docs/releases/v0.1.9.md

@@ -0,0 +1,19 @@
+# v0.1.9
+
+照片来源通过 Synology Photos API 按账号权限读取，共享/个人空间、人物 any/all 筛选和有界 XL 预览缓存可用。生产拒绝文件系统照片来源及 /photos 挂载；本地上传、生成图片和 Server 本地图库继续保留。NAS 原图下载接口曾被拒绝，本版不宣称支持原图下载。
+
+自动化新增 1～10080 分钟的真实间隔，跨整点与跨天不按 Cron 字段重置，既有 Cron 任务保持原样。显示时长明确为到期恢复期限。统一来源快捷创建任务编辑器，改善登录及来源表单响应式布局、设备显示名与历史记录中英文；诊断详情保留原始标识。
+
+## 生产部署
+
+生产已迁至 Ubuntu Server，由 systemd 管理 Docker；业务、Docker 数据和恢复资料位于 T7，并有 UUID 与挂载依赖保护。NAS 旧 Frame 专属资源已清理且独立复核 PASS。CI 保留隔离验证，移除 NAS 自动生产部署任务，不再向 NAS 发布。
+
+正式发布使用 scripts/server-release.py：仅在既有 Ubuntu Server 环境运行，从已提交源码包构建，校验依赖锁、源码哈希、T7 UUID、容器安全约束和真实写入设置；备份 SQLite、配置及 Compose 后切换镜像，失败恢复旧 Compose，不自动回写旧数据库。它不执行上传、显示、删除或恢复图片等设备操作。成功后记录正式提交号、保存源码包及审计回执，删除本次暂存目录；白名单内的 Frame 旧迁移输入归档到本次 recovery，清除无恢复引用的临时镜像别名，共享 Console 资料不动。旧镜像及历史恢复资料保留供回滚，不执行全局 prune。
+
+脚本要求由 git archive 生成的源码放在 /srv/pigway/migration-inbox 的独立子目录；目录内同时提供 RELEASE_COMMIT、RELEASE_HASHES.json 和原始 source.tar.gz。哈希清单涵盖源码与源码包，不含自身。执行 sudo python3 <暂存目录>/scripts/server-release.py；成功后读取 /srv/pigway/apps/pigway-frame-flow/release-verification.json 并独立检查线上接口。
+
+## 验收范围
+
+完整后端测试、静态检查与桌面/平板/手机的中英文浏览器回归纳入发布检查。线上历史补丁已核验，真实写入保持开启；本轮正式发布不重复真实设备写入测试。隔离浏览器验证与真实设备写入证据分别记录于 docs/verification/2026-10-17-final-audit.md。
+
+局域网 HTTPS、独立加密备份及恢复演练仍是后续工作；T7 recovery 不属于独立备份。没有执行 USB 断连、服务器重启或压力测试。

docs/research/KOKONNA_LOCAL_CONTROL.md

@@ -0,0 +1,84 @@
+# KoKonna local-control investigation
+
+Reviewed 2026-10-06. No frame writes, network changes, or firmware changes.
+
+## Sources and limits
+
+- Official FAQ: https://kokonna.art/pages/faq explicitly describes Bluetooth
+  upload and switching. This is a product-level claim, not verified B101 behavior.
+- Public OpenAPI: https://kokonna.art/pages/openapi documents cloud HTTPS calls.
+- Existing official Android nightly 1.6.5 APK from the prior download:
+  SHA256 `8f611bf74bbda70e7e7a5d087e4065dc6000849dcd2f12538d5ff5017c91e1c0`.
+  Static inspection of its packaged app-service.js; no vendor code is copied here.
+- Searches found community API clients, but no verified B101 firmware source or
+  documented bring-your-own-server configuration. Absence from search is not
+  proof that firmware source or another configuration path does not exist.
+
+## Observed client behavior
+
+The account client uses `https://robot.galaxyguide.cn/api/rpc`. Its Bluetooth
+upload flow calls `appFrame.uploadImage` with base64 and `synced: true`, receives
+an image ID, downloads the resulting image from the vendor server, and sends
+the bytes to the frame over BLE. Therefore this observed flow still exposes
+the original image to the vendor cloud.
+
+BLE service UUID: `4fafc201-1fb5-459e-8fcc-c5c9c331914b`.
+Characteristic UUID: `beb5483e-36e1-4688-b7f5-ea07361b26a7`.
+
+Observed JSON commands include `get_info`, `refresh_image`, and `set_image`.
+Image transfer uses start metadata (ID, rotation, type, size, chunk count),
+numbered binary chunks, sync acknowledgements/missing-chunk information, and
+an end command. The client chooses `y4` for firmware starting with B103 and
+`jpg` otherwise. That makes local JPEG transmission a plausible B101 research
+path, not a proven implementation: cloud-independent IDs, processing, firmware
+acceptance, pairing and completion semantics still require validation.
+
+The observed `set_config` payload contains `slideType`, `slideMinute`, and
+`nickname`; `set_wifi` contains SSID and password. No server-host setter was
+found in these paths or common host-setting symbol searches.
+
+## Host replacement assessment
+
+Changing Frame Flow's API base URL changes where Frame Flow sends requests,
+not where the frame connects. Replacing the frame's cloud server requires its
+device-side protocol and a supported address-setting mechanism or firmware
+change. DNS redirection alone may fail HTTPS certificate validation and still
+requires a compatible server implementation. TLS/pinning and actual device
+polling transport have not been established from this APK.
+
+Next read-only step: inspect BLE `get_info` and installed firmware compatibility.
+Any subsequent local image write needs a separate controlled test. No BLE driver
+is enabled by this investigation.
+
+## Wi-Fi-only follow-up
+
+The user excluded Bluetooth and additional gateways. The target is NAS-to-frame
+Wi-Fi control with the original hardware.
+
+GitHub's public repository search for `kokonna` returned three repositories:
+`patrickchen914/kokonna`, `nixihz/kokonna-skill`, and
+`zhengweiran66-eng/kokonna-product.html`. These provide a Home Assistant cloud
+integration, an OpenAPI CLI, and a product page, respectively; no verified B101
+device firmware or Wi-Fi local-server implementation was identified.
+
+Static APK checks found no hard-coded private IPv4 target, WebSocket URL,
+custom image-URL setter, or common server-host setter symbols in app-service.js.
+This does not exclude hidden firmware features or native-library code paths.
+`app.getFirmwares` is called with `robotId`. Upgrade submission passes a firmware
+name, locale and distributor ID through `app.setUpgradeFirmware`; the inspected
+UI does not supply a user-selected firmware download URL. Neither method was
+called during this investigation. Existing account RPC allowlists remain intact.
+
+Candidate paths, none yet verified:
+
+1. A device-local HTTP/TCP service: requires a confirmed frame LAN address and
+   bounded service inspection while the frame is awake.
+2. A firmware-supported custom server or image URL: requires configuration or
+   firmware evidence, not simply replacing the application's API host.
+3. A NAS implementation of the device's cloud protocol: requires the actual
+   polling/download protocol and address/TLS behavior. Passive observation at
+   the existing gateway may provide evidence; a normal NAS on a switched LAN
+   cannot assume it sees another device's outbound packets.
+
+No DNS redirection, router interception, certificate replacement, firmware
+upgrade, reset, or automatic display change was performed.

pigway_frame_flow/api/app.py

@@ -33,6 +33,7 @@ from pigway_frame_flow.models import (
     CurrentDisplay,
     DeleteRequest,
     Device,
+    DeviceIdentity,
     DisplayRequest,
     ErrorResponse,
     Fit,
@@ -123,9 +124,9 @@ def create_app(settings=None, start_worker=True):
         for code in [400, 401, 403, 404, 409, 413, 422, 429, 500, 502, 503]
     }
     app = FastAPI(
-        title="Pigway Frame Flow API",
+        title="PIGWay Frame Flow API",
         docs_url=None,
-        version="0.1.6",
+        version="0.1.17",
         lifespan=lifespan,
         responses=error_responses,
     )
@@ -304,6 +305,7 @@ def create_app(settings=None, start_worker=True):
     )
     def device(device_id: str, refresh: bool = False):
         d = registry.get(device_id).device(refresh)
+        service.clear_self_restore_reference(device_id, d)
         state = db.one("SELECT * FROM device_state WHERE device_id=?", (device_id,))
         possible = bool(
             state
@@ -419,12 +421,19 @@ def create_app(settings=None, start_worker=True):
                 raise FlowError(E.INVALID_REQUEST, "Invalid cloud image") from None
         if thumbnail:
             thumb = cached.with_name(cached.stem + "-thumb.jpg")
-            if not thumb.exists():
-                from PIL import Image
+            from PIL import Image
 
-                with Image.open(cached) as img:
-                    img.thumbnail((300, 400))
-                    img.save(thumb, "JPEG")
+            with Image.open(cached) as img:
+                # The 430px cards need up to 860px on 2x displays. Replace the
+                # existing cache in place so old 300px previews are upgraded.
+                expected_edge = min(860, max(img.size))
+                regenerate = not thumb.exists()
+                if not regenerate:
+                    with Image.open(thumb) as existing:
+                        regenerate = max(existing.size) != expected_edge
+                if regenerate:
+                    img.thumbnail((860, 860), Image.Resampling.LANCZOS)
+                    img.convert("RGB").save(thumb, "JPEG", quality=88, optimize=True)
             return FileResponse(thumb, media_type="image/jpeg")
         from PIL import Image
 
@@ -942,6 +951,7 @@ def create_app(settings=None, start_worker=True):
     )
     def delete_job(job_id: str):
         db.execute("DELETE FROM jobs WHERE id=?", (job_id,))
+        db.execute("DELETE FROM app_config WHERE key=?", ("upload-retry:" + job_id,))
         return Response(status_code=204)
 
     @app.get(
@@ -1002,6 +1012,14 @@ def create_app(settings=None, start_worker=True):
     def settings_view():
         return SettingsView(
             storage_name=settings.storage_name,
+            # Page navigation needs device identity, not a fresh cloud status request.
+            device_catalog=[
+                DeviceIdentity(
+                    id=id,
+                    name=getattr(getattr(driver, "cached", None), "name", id),
+                )
+                for id, driver in registry.drivers.items()
+            ],
             gallery_destinations=[
                 GalleryDestination(
                     id="cloud",
@@ -1022,7 +1040,7 @@ def create_app(settings=None, start_worker=True):
                     supports_upload=True,
                 ),
             ],
-            version="0.1.6",
+            version="0.1.17",
             mock=settings.mock,
             write_enabled=settings.write_enabled,
             api_key_configured=bool(settings.api_key)
@@ -1251,7 +1269,7 @@ def create_app(settings=None, start_worker=True):
     def api_docs():
         response = get_swagger_ui_html(
             openapi_url="/openapi.json",
-            title="Pigway Frame Flow · API Docs",
+            title="PIGWay Frame Flow · API Docs",
             swagger_js_url="/ui/swagger-ui-bundle.js",
             swagger_css_url="/ui/swagger-ui.css",
             swagger_favicon_url='data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg"/>',

pigway_frame_flow/display/cloud_library.py

@@ -13,18 +13,29 @@ class CloudLibrary:
 
     def register(self, device_id, image_id, asset_id, operation_id):
         operation = self.db.one(
-            "SELECT payload FROM operations WHERE id=?", (operation_id,)
+            "SELECT payload,client_id FROM operations WHERE id=?", (operation_id,)
         )
         payload = json.loads(operation["payload"])
         content = payload.get("content", {})
         job = self.db.one(
             "SELECT job_id FROM job_runs WHERE operation_id=?", (operation_id,)
         )
+        if not job and operation["client_id"] == "scheduler-retry":
+            job = self.db.one(
+                "SELECT job_id FROM asset_metadata WHERE asset_id=? AND job_id IS NOT NULL",
+                (asset_id,),
+            )
+        job_config = (
+            self.db.one("SELECT payload FROM jobs WHERE id=?", (job["job_id"],))
+            if job
+            else None
+        )
+        source = json.loads(job_config["payload"])["source"] if job_config else content
         job_id = (
             job["job_id"]
             if job
-            and content.get("type") in ("photo_source", "auto_collage")
-            and content.get("item_id") is None
+            and source.get("type") in ("photo_source", "auto_collage")
+            and source.get("item_id") is None
             else None
         )
         self.db.execute(

pigway_frame_flow/display/service.py

@@ -115,7 +115,7 @@ class DisplayService:
                         )
                     return existing["operation_id"]
             if (
-                action not in ("render", "render-ai", "local-upload")
+                action not in ("display", "render", "render-ai", "local-upload")
                 and tx.execute(
                     "SELECT id FROM operations WHERE device_id=? AND status='UNKNOWN' AND write_started=1 AND action!='render-ai' LIMIT 1",
                     (device_id,),
@@ -187,6 +187,13 @@ class DisplayService:
                 id,
             ),
         )
+        if status == "COMPLETED":
+            row = self.db.one("SELECT result FROM operations WHERE id=?", (id,))
+            asset_id = json.loads(row["result"] or "{}").get("rendered_asset_id")
+            if asset_id and self.db.one(
+                "SELECT id FROM assets WHERE id=?", (asset_id,)
+            ):
+                self.assets.promote(asset_id)
         if status in ("COMPLETED", "FAILED"):
             self.recovery.resolve(id)
 
@@ -205,12 +212,38 @@ class DisplayService:
         )
         return self.db.one("SELECT * FROM device_state WHERE device_id=?", (id,))
 
-    def content_asset(self, content, device_id=None, operation_id=None):
+    def clear_self_restore_reference(self, device_id, device):
+        # A confirmed return to the managed image consumes its restore target.
+        # Keep references while an override or an uncertain write still needs them.
+        image_id = device.current_content.id
+        if (
+            device.status == "offline"
+            or not device.current_content.synced
+            or image_id is None
+        ):
+            return
+        with self.lock:
+            self.db.execute(
+                """UPDATE device_state SET previous_image_id=NULL
+                WHERE device_id=? AND previous_image_id=? AND managed_image_id=?
+                AND base_image_id IS NULL
+                AND NOT EXISTS (SELECT 1 FROM overrides WHERE device_id=?)
+                AND NOT EXISTS (SELECT 1 FROM operations WHERE device_id=?
+                    AND write_started=1 AND status IN ('UPLOADING','SYNCING','UNKNOWN'))""",
+                (device_id, image_id, image_id, device_id, device_id),
+            )
+
+    def content_asset(
+        self, content, device_id=None, operation_id=None, *, staging=False
+    ):
         if isinstance(content, AutoCollageContent):
             from pigway_frame_flow.extensions.auto_collage import prepare
 
             return self.content_asset(
-                prepare(self, content, device_id), device_id, operation_id
+                prepare(self, content, device_id),
+                device_id,
+                operation_id,
+                staging=staging,
             )
         if isinstance(content, ProviderContent):
             values = {**content.data, **self.providers.get(content.provider_id)}
@@ -223,11 +256,14 @@ class DisplayService:
                 ),
                 device_id,
                 operation_id,
+                staging=staging,
             )
         if isinstance(content, TemplateContent):
             values = self.renderer.resolve(content.template, content.data)
             data = self.renderer.render(content.template, values, content.profile)
-            asset = self.assets.put(data, content.template + ".jpg", "generated")
+            asset = self.assets.put(
+                data, content.template + ".jpg", "cache" if staging else "generated"
+            )
             source = {
                 "type": "template",
                 "template": content.template,
@@ -356,7 +392,24 @@ class DisplayService:
                         "UPDATE operations SET result=? WHERE id=?",
                         (encode({"photo_attempts": attempts}), operation_id),
                     )
-                return self.assets.put(rendered, name)
+                asset = self.assets.put(
+                    rendered, name, "cache" if staging else "images"
+                )
+                self.db.execute(
+                    "INSERT OR REPLACE INTO asset_sources VALUES(?,?)",
+                    (
+                        asset["asset_id"],
+                        encode(
+                            {
+                                "type": "photo_source",
+                                "source_id": content.source_id,
+                                "item_id": item["id"],
+                                "source_path": item.get("source_path"),
+                            }
+                        ),
+                    ),
+                )
+                return self.assets.info(asset["asset_id"])
             raise FlowError(
                 E.INVALID_REQUEST, "No decodable photo found within 5 candidates"
             )
@@ -369,11 +422,14 @@ class DisplayService:
         else:
             raise FlowError(E.INVALID_REQUEST, "Content requires renderable image data")
         return self.assets.put(
-            convert(data, content.fit, content.profile), content.name
+            convert(data, content.fit, content.profile),
+            content.name,
+            "cache" if staging else "images",
         )
 
     def current_content(self, device_id):
         device = self.registry.get(device_id).device()
+        self.clear_self_restore_reference(device_id, device)
         image_id = device.current_content.id
         row = self.db.one(
             "SELECT * FROM image_sources WHERE device_id=? AND image_id=?",
@@ -424,10 +480,38 @@ class DisplayService:
             yield from rows
             cursor_time, cursor_id = rows[-1]["created_at"], rows[-1]["id"]
 
+    def upload_retry_expired(self, op):
+        if op["client_id"] != "scheduler-retry" or not op["request_id"].startswith(
+            "upload-retry-"
+        ):
+            return False
+        root = op["request_id"].split("-")[-2]
+        for row in self.db.all(
+            "SELECT payload FROM app_config WHERE key LIKE 'upload-retry:%'"
+        ):
+            plan = json.loads(row["payload"])
+            if plan["root"] == root:
+                return now_iso() >= plan["deadline"]
+        return True
+
     def process_one(self):
         with self.lock:
             for op in self.queued_operations():
+                if self.upload_retry_expired(op):
+                    self.update(
+                        op["id"],
+                        "FAILED",
+                        error={
+                            "code": E.CONFLICT,
+                            "message": "Upload retry window closed",
+                            "request_id": op["request_id"],
+                            "details": {"reason": "RETRY_WINDOW_CLOSED"},
+                        },
+                    )
+                    self.db.history(op, "RETRY_WINDOW_CLOSED")
+                    continue
                 if op["action"] not in (
+                    "display",
                     "render",
                     "render-ai",
                     "local-upload",
@@ -511,6 +595,8 @@ class DisplayService:
         previous = device.current_content.id
         state = self.state(device_id)
         if action == "delete":
+            self.clear_self_restore_reference(device_id, device)
+            state = self.state(device_id)
             image_id = payload["image_id"]
             if payload.get("cloud_cleanup"):
                 if (
@@ -549,7 +635,12 @@ class DisplayService:
                 )
             }
             if image_id in protected and not payload.get("purge"):
-                raise FlowError(E.CONFLICT, "Image is needed for restoration", 409)
+                raise FlowError(
+                    E.CONFLICT,
+                    "Image is needed for restoration",
+                    409,
+                    {"reason": "RESTORE_IMAGE_PROTECTED"},
+                )
             if image_id == previous and not payload["confirm_current"]:
                 raise FlowError(E.CONFLICT, "Current image needs confirmation", 409)
             self._start_write(id)
@@ -603,6 +694,13 @@ class DisplayService:
             self.update(id, "SYNCING", {"image_id": target})
             self.db.history(op, "ACCEPTED")
             return
+        # A new upload is independent of a previous failed write. Read back its
+        # outcome before closing the old attempt; never replay that operation.
+        for pending in self.db.all(
+            "SELECT id FROM operations WHERE device_id=? AND status='UNKNOWN' AND write_started=1 AND action='display'",
+            (device_id,),
+        ):
+            self.reconcile(pending["id"], acknowledge=True)
         request = DisplayRequest.model_validate(payload)
         content = request.content
         self.update(id, "RENDERING")
@@ -619,7 +717,7 @@ class DisplayService:
                     )
                 image_id = matches[0].image_id
         else:
-            asset = self.content_asset(content, device_id, id)
+            asset = self.content_asset(content, device_id, id, staging=True)
             self.assets.record_origin(asset["asset_id"], op)
             image_id = None
         self.db.execute(
@@ -654,7 +752,6 @@ class DisplayService:
             driver.display(image_id)
         result = {"image_id": image_id}
         if asset:
-            self.assets.promote(asset["asset_id"])
             result["rendered_asset_id"] = asset["asset_id"]
             source = self.db.one(
                 "SELECT payload FROM asset_sources WHERE asset_id=?",
@@ -741,6 +838,7 @@ class DisplayService:
                     and device.current_content.synced
                 ):
                     self.update(op["id"], "COMPLETED")
+                    self.clear_self_restore_reference(op["device_id"], device)
                     self.cloud_library.confirm(op["id"])
                     self.db.history(op, "COMPLETED")
                     self.db.event("operation.completed", {"operation_id": op["id"]})
@@ -766,6 +864,7 @@ class DisplayService:
                     and device.current_content.synced
                 ):
                     self.update(op["id"], "COMPLETED")
+                    self.clear_self_restore_reference(op["device_id"], device)
                     self.cloud_library.confirm(op["id"])
                     self.db.history(op, "COMPLETED")
                     self.db.event("operation.completed", {"operation_id": op["id"]})

pigway_frame_flow/display/upload_reconciliation.py

@@ -77,7 +77,6 @@ class UploadReconciliation:
             result["image_id"] = expected
             result["upload_confirmed"] = True
             service.update(op["id"], "UNKNOWN", result, json.loads(op["error"] or "{}"))
-            service.assets.promote(result["rendered_asset_id"])
             source = service.db.one(
                 "SELECT payload FROM asset_sources WHERE asset_id=?",
                 (result["rendered_asset_id"],),

pigway_frame_flow/drivers/kokonna/client.py

@@ -10,6 +10,7 @@ from collections import deque
 from urllib.parse import quote
 
 import requests
+from urllib3.exceptions import MaxRetryError, NewConnectionError
 
 from pigway_frame_flow.errors import ErrorCode as E
 from pigway_frame_flow.errors import FlowError
@@ -124,7 +125,15 @@ class SafeTransport:
                 ),
                 "request_error",
             )
-            not_sent = isinstance(exc, requests.ConnectTimeout)
+            # A socket/DNS establishment failure precedes the HTTP write. A
+            # dropped established connection still has an uncertain outcome.
+            not_sent = isinstance(exc, requests.ConnectTimeout) or any(
+                isinstance(cause, MaxRetryError)
+                and isinstance(cause.reason, NewConnectionError)
+                for cause in exc.args
+            )
+            if not_sent and category == "connection_error":
+                category = "connect_error"
             uncertain = write and not not_sent
             raise FlowError(
                 E.WRITE_RESULT_UNKNOWN if uncertain else E.CLOUD_UNAVAILABLE,

pigway_frame_flow/extensions/storage.py

@@ -43,6 +43,7 @@ class LocalRetention:
             "SELECT payload FROM jobs",
             "SELECT payload FROM template_config",
             "SELECT payload FROM operations WHERE status IN ('QUEUED','RENDERING','UPLOADING','SYNCING','UNKNOWN')",
+            "SELECT payload FROM app_config WHERE key LIKE 'upload-retry:%'",
         ]:
             payloads += [row["payload"] for row in db.all(query)]
         for payload in payloads:

pigway_frame_flow/models.py

@@ -265,7 +265,10 @@ class GalleryImage(BaseModel):
 
 
 class Schedule(StrictModel):
-    type: Literal["cron", "daily", "weekdays", "weekends", "date", "temporary"]
+    type: Literal[
+        "cron", "daily", "weekdays", "weekends", "date", "temporary", "interval"
+    ]
+    interval_minutes: int | None = Field(default=None, ge=1, le=10080)
     cron: str | None = None
     time: str | None = Field(default=None, pattern=r"^([01]\d|2[0-3]):[0-5]\d$")
     at: datetime | None = None
@@ -342,9 +345,15 @@ class GalleryDestination(BaseModel):
     supports_upload: bool = False
 
 
+class DeviceIdentity(BaseModel):
+    id: str
+    name: str
+
+
 class SettingsView(BaseModel):
     storage_name: str = "NAS"
     gallery_destinations: list[GalleryDestination] = Field(default_factory=list)
+    device_catalog: list[DeviceIdentity] = Field(default_factory=list)
     version: str
     mock: bool
     write_enabled: bool
@@ -357,7 +366,7 @@ class SettingsView(BaseModel):
 
 class Health(BaseModel):
     status: str
-    version: str = "0.1.6"
+    version: str = "0.1.17"
 
 
 class Readiness(BaseModel):
@@ -366,6 +375,7 @@ class Readiness(BaseModel):
 
 
 class Asset(BaseModel):
+    source_path: str | None = None
     starred: bool = False
     origin: Literal["manual", "task", "external", "template", "unknown"] = "unknown"
     job_id: str | None = None
@@ -386,8 +396,8 @@ class RestoreRequest(StrictModel):
 
 
 class Version(BaseModel):
-    product: str = "Pigway Frame Flow"
-    version: str = "0.1.6"
+    product: str = "PIGWay Frame Flow"
+    version: str = "0.1.17"
     api_version: str = "v1"
     commit: str = "development"
     build_time: str = "unknown"

pigway_frame_flow/providers/photo_sources.py

@@ -2,6 +2,7 @@
 
 import base64
 import json
+import logging
 import os
 import posixpath
 import random
@@ -27,8 +28,11 @@ from pigway_frame_flow.storage.database import encode
 
 class PhotoSourceInput(StrictModel):
     name: str = Field(min_length=1, max_length=120)
-    kind: Literal["local", "webdav", "google-drive", "alipan", "baidu"]
+    kind: Literal[
+        "local", "synology-photos", "webdav", "google-drive", "alipan", "baidu"
+    ]
     location: str = Field(min_length=1, max_length=2048)
+    nas_root_path: str | None = Field(default=None, max_length=2048, pattern=r"^/")
     recursive: bool = True
     enabled: bool = True
     catalog_limit: int = Field(default=10000, ge=1, le=100000)
@@ -36,6 +40,8 @@ class PhotoSourceInput(StrictModel):
     organized_only: bool = False
     folder_caption: bool = False
     orientation: Literal["auto", "landscape", "portrait"] | None = None
+    minimum_short_edge: int = Field(default=0, ge=0, le=50000)
+    minimum_long_edge: int = Field(default=0, ge=0, le=50000)
     minimum_sharpness: float = Field(default=0, ge=0, le=10000)
     minimum_brightness: float = Field(default=0, ge=0, le=255)
     maximum_brightness: float = Field(default=255, ge=0, le=255)
@@ -57,6 +63,7 @@ class PhotoItem(StrictModel):
     id: str
     name: str
     caption: dict[str, str] | None = None
+    source_path: str | None = None
     provider_preview: bool = False
     orientation: Literal["landscape", "portrait", "square"] | None = None
     width: int | None = None
@@ -77,6 +84,7 @@ class PhotoSources:
     def __init__(self, db, settings, assets):
         self.db, self.settings, self.assets = db, settings, assets
         self.cache = {}
+        self.api_items = {}
         self.synology = SynologyPhotos(settings)
         # Register provider secrets before request IDs or errors can be reflected.
         for row in self.list():
@@ -106,22 +114,33 @@ class PhotoSources:
             raise FlowError(E.NOT_FOUND, "Photo source not found", 404)
         return PhotoSourceInput.model_validate_json(row["payload"])
 
+    @staticmethod
+    def require_api_source(source):
+        # Block persisted legacy sources as well as new requests, before any disk read.
+        if source.kind == "local":
+            raise FlowError(
+                E.FORBIDDEN,
+                "Filesystem photo sources are disabled; use the Synology Photos API",
+                403,
+            )
+
     def save(self, source_id, source):
+        self.require_api_source(source)
         if source.minimum_brightness > source.maximum_brightness:
             raise FlowError(E.INVALID_REQUEST, "Brightness range is reversed")
-        if source.kind != "local" and (
+        if source.kind not in ("local", "synology-photos") and (
             source.organized_only or source.folder_caption or source.synology_previews
         ):
             raise FlowError(
                 E.UNSUPPORTED_CAPABILITY,
                 "Folder captions and Synology previews require a local photo source",
             )
-        if source.orientation and source.kind != "local":
+        if source.orientation and source.kind not in ("local", "synology-photos"):
             raise FlowError(
                 E.UNSUPPORTED_CAPABILITY,
                 "Orientation filtering requires a local photo source",
             )
-        if source.people_filter and source.kind != "local":
+        if source.people_filter and source.kind not in ("local", "synology-photos"):
             raise FlowError(
                 E.INVALID_REQUEST,
                 "Person filtering requires a local Synology photo source",
@@ -140,6 +159,21 @@ class PhotoSources:
                 raise FlowError(
                     E.INVALID_REQUEST, "Local sources do not use credentials"
                 )
+        elif source.kind == "synology-photos":
+            location = source.location.strip("/")
+            if location == ".":
+                location = ""
+            if "\\" in location or any(p in (".", "..") for p in location.split("/")):
+                raise FlowError(
+                    E.INVALID_REQUEST,
+                    "Photos API folder must be a relative folder path or root",
+                )
+            if source.credential_env or source.synology_previews:
+                raise FlowError(
+                    E.INVALID_REQUEST,
+                    "Photos API sources use the shared Photos session and XL thumbnail download",
+                )
+            source = source.model_copy(update={"location": location or "."})
         elif source.kind == "webdav":
             source = source.model_copy(
                 update={
@@ -169,6 +203,7 @@ class PhotoSources:
             ("photo_source:" + source_id, encode(source.model_dump())),
         )
         self.cache.pop(source_id, None)
+        self.api_items.pop(source_id, None)
         return dict(source.model_dump(), id=source_id)
 
     def delete(self, source_id):
@@ -186,6 +221,7 @@ class PhotoSources:
             "DELETE FROM app_config WHERE key=?", ("photo_source:" + source_id,)
         )
         self.cache.pop(source_id, None)
+        self.api_items.pop(source_id, None)
 
     def local_directory(self, location):
         root = self.settings.photo_root.resolve()
@@ -264,8 +300,12 @@ class PhotoSources:
 
     def catalog(self, source_id, refresh=False, *, target_size=(1200, 1600)):
         source = self.get(source_id)
+        self.require_api_source(source)
         if not source.enabled:
             raise FlowError(E.CONFLICT, "Photo source is disabled", 409)
+        session_identity = (
+            self.synology.sid() if source.kind == "synology-photos" else None
+        )
         wanted = (
             orientation(*target_size)
             if source.orientation == "auto"
@@ -277,6 +317,7 @@ class PhotoSources:
             and not refresh
             and time.monotonic() - cached[0] < 60
             and cached[2] == wanted
+            and cached[3] == session_identity
         ):
             return cached[1]
         allowed = (
@@ -286,7 +327,7 @@ class PhotoSources:
                 refresh=refresh,
                 space=source.people_space,
             )
-            if source.people_filter
+            if source.people_filter and source.kind == "local"
             else None
         )
         items = []
@@ -375,6 +416,8 @@ class PhotoSources:
                                         height,
                                     )
                                 )
+                            if not self.resolution_matches(source, width, height):
+                                continue
                             direction = orientation(width, height)
                             if wanted and direction != wanted:
                                 continue
@@ -406,6 +449,67 @@ class PhotoSources:
                         break
                 if len(items) >= source.catalog_limit:
                     break
+        elif source.kind == "synology-photos":
+            self.synology.sid()
+            rows = self.synology.items(
+                source.person_ids if source.people_filter else [],
+                source.person_match,
+                space=source.people_space,
+                limit=100000,
+            )
+            location = "" if source.location == "." else source.location.strip("/")
+            self.api_items[source_id] = {}
+            for row in rows:
+                folder = row.get("additional", {}).get("folder")
+                if isinstance(folder, dict):
+                    folder = folder.get("name")
+                if not isinstance(folder, str) or not isinstance(
+                    row.get("filename"), str
+                ):
+                    raise FlowError(
+                        E.CLOUD_UNAVAILABLE,
+                        "Photos API response lacks folder or filename",
+                        502,
+                    )
+                relative = folder.strip("/") + "/" + row["filename"]
+                if location and not relative.startswith(location + "/"):
+                    continue
+                if not source.recursive and folder.strip("/") != location:
+                    continue
+                caption = path_caption(relative)
+                if source.organized_only and caption is None:
+                    continue
+                size = row.get("additional", {}).get("resolution", {})
+                width, height = size.get("width", 0), size.get("height", 0)
+                rotation = row.get("additional", {}).get("orientation", 1)
+                if rotation in (5, 6, 7, 8):
+                    width, height = height, width
+                if not self.resolution_matches(source, width, height):
+                    continue
+                direction = orientation(width, height)
+                if wanted and (not width or not height or direction != wanted):
+                    continue
+                items.append(
+                    {
+                        "id": str(row["id"]),
+                        "name": row["filename"],
+                        "provider_preview": True,
+                        "source_path": (
+                            source.nas_root_path.rstrip("/")
+                            + "/"
+                            + relative.lstrip("/")
+                            if source.nas_root_path
+                            else "/" + relative.lstrip("/")
+                        ),
+                        "caption": caption if source.folder_caption else None,
+                        "width": width,
+                        "height": height,
+                        "orientation": direction,
+                    }
+                )
+                self.api_items[source_id][str(row["id"])] = row
+                if len(items) >= source.catalog_limit:
+                    break
         elif source.kind in ("google-drive", "alipan", "baidu"):
             from pigway_frame_flow.providers.cloud_drives import CloudDrives
 
@@ -468,9 +572,14 @@ class PhotoSources:
                     "INSERT OR REPLACE INTO photo_dimensions(path,mtime,bytes,width,height) VALUES(?,?,?,?,?)",
                     size_updates,
                 )
-        self.cache[source_id] = (time.monotonic(), items, wanted)
+        self.cache[source_id] = (time.monotonic(), items, wanted, session_identity)
         return items
 
+    @staticmethod
+    def resolution_matches(source, width, height):
+        short, long = sorted((width, height))
+        return short >= source.minimum_short_edge and long >= source.minimum_long_edge
+
     def read(self, source_id, item_id=None, *, target_size=(1200, 1600)):
         source = self.get(source_id)
         items = self.catalog(source_id, target_size=target_size)
@@ -526,6 +635,25 @@ class PhotoSources:
                     os.close(parent_fd)
             except OSError:
                 raise FlowError(E.NOT_FOUND, "Photo is unavailable", 404) from None
+        elif source.kind == "synology-photos":
+            data = self.synology.download(
+                self.api_items[source_id][item["id"]], space=source.people_space
+            )
+            if source.folder_caption:
+                caption = dict(item.get("caption") or {})
+                try:
+                    caption["people"] = " & ".join(
+                        self.synology.item_people(item["id"], space=source.people_space)
+                    )
+                except FlowError:
+                    # Optional labels must not prevent displaying a valid photo.
+                    logging.getLogger(__name__).warning(
+                        "Photos person labels unavailable; keeping photo caption"
+                    )
+                item = {
+                    **item,
+                    "caption": {k: v for k, v in caption.items() if v} or None,
+                }
         elif source.kind in ("google-drive", "alipan", "baidu"):
             from pigway_frame_flow.providers.cloud_drives import CloudDrives
 
@@ -534,4 +662,15 @@ class PhotoSources:
             data = self.assets.fetch_url(item["id"], headers=self.headers(source))
         if len(data) > self.settings.max_bytes:
             raise FlowError(E.INVALID_REQUEST, "Image exceeds size limit")
+        if source.minimum_short_edge or source.minimum_long_edge:
+            from io import BytesIO
+
+            from PIL import Image
+
+            with Image.open(BytesIO(data)) as image:
+                if not self.resolution_matches(source, *image.size):
+                    raise FlowError(
+                        E.INVALID_REQUEST,
+                        "Photo is below the configured minimum resolution",
+                    )
         return data, item["name"], item.get("caption")

pigway_frame_flow/providers/photos_cache.py

@@ -0,0 +1,84 @@
+"""Bounded, process-safe cache for individually requested Photos images."""
+
+import fcntl
+import hashlib
+import os
+import tempfile
+import time
+from pathlib import Path
+
+from PIL import Image
+
+from pigway_frame_flow.errors import ErrorCode as E
+from pigway_frame_flow.errors import FlowError
+from pigway_frame_flow.renderers.images import MAX_IMAGE_PIXELS
+
+
+class PhotosCache:
+    def __init__(self, settings):
+        self.root = settings.data_dir / "cache" / "synology-photos"
+        self.capacity = settings.photos_cache_bytes
+        self.max_bytes = min(settings.max_bytes, self.capacity)
+        self.hits = 0
+        self.downloads = 0
+
+    def _prune(self, reserve=0):
+        entries = []
+        for path in self.root.iterdir():
+            if path.name.endswith(".part"):
+                path.unlink(missing_ok=True)
+            elif path.suffix == ".image" and not path.is_symlink():
+                entries.append(path)
+        entries.sort(key=lambda p: p.stat().st_mtime_ns)
+        total = sum(p.stat().st_size for p in entries)
+        for path in entries:
+            if total + reserve <= self.capacity:
+                break
+            total -= path.stat().st_size
+            path.unlink()
+
+    def read(self, key, download):
+        self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        identity = hashlib.sha256(key.encode()).hexdigest()
+        path = self.root / (identity + ".image")
+        # One lock bounds total disk use and coalesces same-item downloads across
+        # threads/processes. The lock file is constant, not one file per photo.
+        with (self.root / ".lock").open("a+b") as lock:
+            fcntl.flock(lock, fcntl.LOCK_EX)
+            self._prune()
+            if path.is_file() and not path.is_symlink():
+                data = path.read_bytes()
+                os.utime(path, None)
+                self.hits += 1
+                return data
+            self._prune(self.max_bytes)
+            fd, temporary = tempfile.mkstemp(suffix=".part", dir=self.root)
+            part = Path(temporary)
+            try:
+                with os.fdopen(fd, "wb") as handle:
+                    download(handle, self.max_bytes, time.monotonic() + 90)
+                    handle.flush()
+                    os.fsync(handle.fileno())
+                if not 0 < part.stat().st_size <= self.max_bytes:
+                    raise ValueError()
+                with Image.open(part) as image:
+                    if image.format not in ("JPEG", "PNG", "WEBP"):
+                        raise ValueError()
+                    if image.width * image.height > MAX_IMAGE_PIXELS:
+                        raise ValueError()
+                    image.verify()
+                # Decode before committing; truncated/compressed-bomb payloads
+                # must never become a reusable cache hit.
+                with Image.open(part) as image:
+                    image.load()
+                part.replace(path)
+                self.downloads += 1
+                return path.read_bytes()
+            except (OSError, ValueError, Image.DecompressionBombError):
+                raise FlowError(
+                    E.CLOUD_UNAVAILABLE,
+                    "Photos download is incomplete or not a supported image",
+                    502,
+                ) from None
+            finally:
+                part.unlink(missing_ok=True)

pigway_frame_flow/providers/synology_photos.py

@@ -119,12 +119,23 @@ class SynologyPhotos:
             result = json.loads(raw)
             if not result.get("success"):
                 code = result.get("error", {}).get("code")
-                if api == "SYNO.API.Auth" or code in (105, 106, 107, 119):
+                if api == "SYNO.API.Auth" or code in (106, 107, 119):
                     if api != "SYNO.API.Auth":
                         self.disconnect()
                     raise FlowError(
                         E.CONFIG_REQUIRED, "Reconnect Synology Photos account", 409
                     )
+                if code in (102, 103, 104):
+                    raise FlowError(
+                        E.UNSUPPORTED_CAPABILITY,
+                        "This NAS Photos API or method is unavailable",
+                    )
+                if code == 105:
+                    raise FlowError(
+                        E.FORBIDDEN,
+                        "Photos account cannot access the selected space",
+                        403,
+                    )
                 raise FlowError(
                     E.CLOUD_UNAVAILABLE, "Synology Photos query was rejected", 502
                 )
@@ -141,7 +152,7 @@ class SynologyPhotos:
             sid = json.loads(self.path.read_text())["sid"]
             if not isinstance(sid, str) or not sid:
                 raise ValueError()
-        except (OSError, ValueError, KeyError):
+        except (OSError, ValueError, KeyError, TypeError):
             raise FlowError(
                 E.CONFIG_REQUIRED, "Connect Synology Photos account first", 409
             ) from None
@@ -269,3 +280,176 @@ class SynologyPhotos:
             )
             self.cache[key] = (time.monotonic(), selected)
             return selected
+
+    def items(self, person_ids=(), mode="any", *, space="shared", limit=10000):
+        """Intersect identities, not filenames, for any/all people selection."""
+        prefix = "SYNO.FotoTeam" if space == "shared" else "SYNO.Foto"
+        if mode not in ("any", "all") or space not in ("shared", "personal"):
+            raise FlowError(E.INVALID_REQUEST, "Invalid Photos selection")
+        with self.lock:
+            self.sid()
+            if person_ids:
+                known = {x["id"] for x in self.people(space)}
+                if not set(person_ids) <= known:
+                    raise FlowError(
+                        E.INVALID_REQUEST, "Selected person no longer exists"
+                    )
+            groups = []
+            for person in person_ids or [None]:
+                rows = self.pages(
+                    prefix + ".Browse.Item",
+                    7,
+                    additional=json.dumps(["folder", "thumbnail", "resolution"]),
+                    **({"person_id": person} if person is not None else {}),
+                )
+                groups.append(
+                    {str(r["id"]): r for r in rows if r.get("type") == "photo"}
+                )
+            selected = set(groups[0])
+            for group in groups[1:]:
+                selected = (
+                    selected & group.keys()
+                    if mode == "all"
+                    else selected | group.keys()
+                )
+            merged = {key: row for group in groups for key, row in group.items()}
+            return [merged[key] for key in sorted(selected, key=int)][:limit]
+
+    def item_people(self, item_id, *, space="shared"):
+        """Reuse verified person albums; never label an unnamed face by its ID."""
+        prefix = "SYNO.FotoTeam" if space == "shared" else "SYNO.Foto"
+        with self.lock:
+            key = ("caption-people", self.sid(), space)
+            cached = self.cache.get(key)
+            if not cached or time.monotonic() - cached[0] >= 900:
+                names: dict[str, list[str]] = {}
+                for person in self.people(space):
+                    if not person["named"]:
+                        continue
+                    for row in self.pages(
+                        prefix + ".Browse.Item", 7, person_id=person["id"]
+                    ):
+                        item_names = names.setdefault(str(row["id"]), [])
+                        if person["name"] not in item_names:
+                            item_names.append(person["name"])
+                self.cache[key] = (time.monotonic(), names)
+            return list(self.cache[key][1].get(str(item_id), []))
+
+    def download(self, row, *, space="shared", rendition="thumbnail"):
+        from pigway_frame_flow.providers.photos_cache import PhotosCache
+
+        sid = self.sid()
+        url, pin = self.endpoint()
+        prefix = "SYNO.FotoTeam" if space == "shared" else "SYNO.Foto"
+        if rendition == "thumbnail":
+            thumb = row.get("additional", {}).get("thumbnail", {})
+            if not thumb.get("cache_key") or not thumb.get("unit_id"):
+                raise FlowError(
+                    E.UNSUPPORTED_CAPABILITY, "Photos thumbnail is unavailable"
+                )
+            api, method = prefix + ".Thumbnail", "get"
+            params = dict(
+                id=thumb["unit_id"],
+                cache_key=thumb["cache_key"],
+                size="xl",
+                type="unit",
+            )
+        else:
+            raise FlowError(
+                E.UNSUPPORTED_CAPABILITY,
+                "Only verified XL thumbnails are supported; original download is unavailable",
+            )
+        if not hasattr(self, "image_cache"):
+            self.image_cache = PhotosCache(self.settings)
+        # Session/endpoint scoping prevents a different account from reusing a
+        # previous account's cached photo. Cache keys never contain raw secrets.
+        identity = hashlib.sha256((sid + str(url.geturl()) + pin).encode()).hexdigest()
+        key = json.dumps(
+            [
+                identity,
+                space,
+                row["id"],
+                rendition,
+                row.get("indexed_time"),
+                row.get("filesize"),
+                row.get("additional", {}).get("thumbnail", {}).get("cache_key"),
+            ]
+        )
+        return self.image_cache.read(
+            key,
+            lambda handle, cap, deadline: self._download(
+                api, method, params, sid, handle, cap, deadline
+            ),
+        )
+
+    def _download(self, api, method, params, sid, handle, cap, deadline):
+        if (api, method) not in {
+            ("SYNO.FotoTeam.Thumbnail", "get"),
+            ("SYNO.Foto.Thumbnail", "get"),
+        }:
+            raise FlowError(E.FORBIDDEN, "Unsupported Photos download", 403)
+        url, pin = self.endpoint()
+        connection = http.client.HTTPSConnection(
+            url.hostname,
+            url.port or 443,
+            timeout=30,
+            context=ssl._create_unverified_context(),
+        )
+        try:
+            connection.connect()
+            certificate = connection.sock.getpeercert(binary_form=True)
+            if not certificate or hashlib.sha256(certificate).hexdigest() != pin:
+                raise FlowError(E.FORBIDDEN, "Synology Photos certificate changed", 403)
+            connection.request(
+                "POST",
+                "/webapi/entry.cgi",
+                urlencode(dict(api=api, method=method, version=2, _sid=sid, **params)),
+                {"Content-Type": "application/x-www-form-urlencoded"},
+            )
+            response = connection.getresponse()
+            if response.status != 200:
+                raise ValueError()
+            if "json" in (response.getheader("Content-Type") or "").lower():
+                result = json.loads(response.read(65537))
+                if result.get("error", {}).get("code") in (106, 107, 119):
+                    self.disconnect()
+                    raise FlowError(
+                        E.CONFIG_REQUIRED, "Reconnect Synology Photos account", 409
+                    )
+                if result.get("error", {}).get("code") == 105:
+                    raise FlowError(
+                        E.FORBIDDEN, "Photos account cannot download this photo", 403
+                    )
+                raise FlowError(
+                    E.CLOUD_UNAVAILABLE, "Photos download was rejected", 502
+                )
+            expected = response.getheader("Content-Length")
+            if expected and int(expected) > cap:
+                raise FlowError(
+                    E.INVALID_REQUEST,
+                    "Photos image exceeds download limit; select thumbnail",
+                )
+            total = 0
+            while True:
+                if time.monotonic() > deadline:
+                    raise TimeoutError()
+                chunk = response.read(min(65536, cap - total + 1))
+                if not chunk:
+                    break
+                total += len(chunk)
+                if total > cap:
+                    raise FlowError(
+                        E.INVALID_REQUEST,
+                        "Photos image exceeds download limit; select thumbnail",
+                    )
+                handle.write(chunk)
+            if expected and total != int(expected):
+                raise ValueError()
+        except (OSError, ValueError, http.client.HTTPException):
+            raise FlowError(
+                E.CLOUD_UNAVAILABLE,
+                "Photos download interrupted; retry explicitly",
+                502,
+            ) from None
+        finally:
+            connection.close()

pigway_frame_flow/renderers/images.py

@@ -1,5 +1,6 @@
 import base64
 import ipaddress
+import json
 import socket
 from io import BytesIO
 from urllib.parse import urlsplit
@@ -115,9 +116,17 @@ class Assets:
     def promote(self, asset_id):
         row = self.db.one("SELECT * FROM assets WHERE id=?", (asset_id,))
         if row and row["kind"] == "cache":
-            target = self.settings.data_dir / "images" / (asset_id + ".jpg")
+            source = self.db.one(
+                "SELECT payload FROM asset_sources WHERE asset_id=?", (asset_id,)
+            )
+            kind = (
+                "generated"
+                if source and json.loads(source["payload"]).get("type") == "template"
+                else "images"
+            )
+            target = self.settings.data_dir / kind / (asset_id + ".jpg")
             self.path(asset_id).replace(target)
-            self.db.execute("UPDATE assets SET kind='images' WHERE id=?", (asset_id,))
+            self.db.execute("UPDATE assets SET kind=? WHERE id=?", (kind, asset_id))
         return self.info(asset_id)
 
     def info(self, asset_id):
@@ -125,7 +134,13 @@ class Assets:
         if not row:
             raise FlowError(E.NOT_FOUND, "Asset not found", 404)
         meta = self.db.one("SELECT * FROM asset_metadata WHERE asset_id=?", (asset_id,))
+        provenance = self.db.one(
+            "SELECT payload FROM asset_sources WHERE asset_id=?", (asset_id,)
+        )
         return {
+            "source_path": json.loads(provenance["payload"]).get("source_path")
+            if provenance
+            else None,
             "starred": bool(meta and meta["starred"]),
             "origin": meta["origin"] if meta else "unknown",
             "job_id": meta["job_id"] if meta else None,

pigway_frame_flow/renderers/photo_caption.py

@@ -41,7 +41,7 @@ def render_captioned_photo(
     draw = ImageDraw.Draw(canvas)
     values = [
         " ".join(str(caption.get(key, "")).split())
-        for key in ("title", "date", "place")
+        for key in ("date", "people", "title", "place")
     ]
     text = " · ".join(value for value in values if value)
     font_size = layout.font_size
@@ -51,8 +51,8 @@ def render_captioned_photo(
         font_size -= 2
         font = font_loader(font_size)
     # Shorten the title before touching the date/location. Never wrap the band.
-    while draw.textlength(text, font=font) > available and len(values[0]) > 2:
-        values[0] = values[0].rstrip("…")[:-1] + "…"
+    while draw.textlength(text, font=font) > available and len(values[2]) > 2:
+        values[2] = values[2].rstrip("…")[:-1] + "…"
         text = " · ".join(value for value in values if value)
     while draw.textlength(text, font=font) > available and len(text) > 2:
         text = text.rstrip("…")[:-1] + "…"

pigway_frame_flow/scheduler/engine.py

@@ -18,11 +18,16 @@ from pigway_frame_flow.models import (
     PlaylistInput,
     RestoreContent,
 )
+from pigway_frame_flow.scheduler.upload_retries import UploadRetries
 from pigway_frame_flow.storage.database import encode, now_iso
 
 
 def next_run(schedule, after=None):
     after = after or datetime.now(UTC)
+    if schedule.type == "interval":
+        if schedule.interval_minutes is None:
+            raise FlowError(E.INVALID_REQUEST, "Interval requires interval_minutes")
+        return (after + timedelta(minutes=schedule.interval_minutes)).isoformat()
     if schedule.type in ("date", "temporary"):
         if not schedule.at or schedule.at.tzinfo is None:
             raise FlowError(E.INVALID_REQUEST, "One-time date must include timezone")
@@ -56,6 +61,7 @@ class Scheduler:
         self.thread = None
         self.webhook_thread = None
         self.tick_lock = threading.Lock()
+        self.upload_retries = UploadRetries(service)
 
     def jobs(self):
         rows = [
@@ -143,6 +149,7 @@ class Scheduler:
     def tick(self, current=None):
         current = current or datetime.now(UTC)
         with self.tick_lock:
+            self.upload_retries.tick(current)
             for row in self.db.all(
                 "SELECT * FROM jobs WHERE enabled=1 AND next_run<=?",
                 (current.isoformat(),),
@@ -179,6 +186,10 @@ class Scheduler:
                                 ),
                             ).model_dump(mode="json")
                         )
+                        if action == "display":
+                            payload = self.upload_retries.scheduled_payload(
+                                row["id"], payload
+                            )
                         operation_id = self.service.submit(
                             action,
                             payload,
@@ -187,6 +198,10 @@ class Scheduler:
                             "schedule-" + uuid4().hex,
                             "job-" + row["id"] + "-" + slot,
                         )
+                        if action == "display":
+                            self.upload_retries.scheduled_submitted(
+                                row["id"], operation_id
+                            )
                     following = next_run(job.schedule, current)
                     enabled = bool(following)
                     updated = job.model_copy(update={"enabled": enabled}).model_dump(

pigway_frame_flow/scheduler/upload_retries.py

@@ -0,0 +1,246 @@
+"""Durable, job-local upload retries; scheduled execution remains authoritative."""
+
+import json
+from datetime import datetime, timedelta
+
+from pigway_frame_flow.errors import FlowError
+from pigway_frame_flow.storage.database import encode
+
+
+class UploadRetries:
+    def __init__(self, service):
+        self.service, self.db = service, service.db
+
+    def load(self, job_id):
+        row = self.db.one(
+            "SELECT payload FROM app_config WHERE key=?", ("upload-retry:" + job_id,)
+        )
+        return json.loads(row["payload"]) if row else None
+
+    def save(self, job_id, plan):
+        if plan is None:
+            self.db.execute(
+                "DELETE FROM app_config WHERE key=?", ("upload-retry:" + job_id,)
+            )
+        else:
+            self.db.execute(
+                "INSERT OR REPLACE INTO app_config VALUES(?,?)",
+                ("upload-retry:" + job_id, encode(plan)),
+            )
+
+    @staticmethod
+    def reuse(payload, asset_id):
+        return {**payload, "content": {"type": "image", "asset_id": asset_id}}
+
+    def scheduled_payload(self, job_id, payload):
+        plan = self.load(job_id)
+        if plan and plan["phase"] in ("extra", "scheduled", "scheduled_running"):
+            return self.reuse(payload, plan["asset_id"])
+        return payload
+
+    def scheduled_submitted(self, job_id, operation_id):
+        plan = self.load(job_id)
+        if plan and plan["phase"] in ("extra", "scheduled", "scheduled_running"):
+            plan.update(phase="scheduled_running", active=operation_id)
+            self.save(job_id, plan)
+
+    def close_unknown(self, operation):
+        if operation["status"] == "UNKNOWN":
+            raw = self.db.one(
+                "SELECT * FROM operations WHERE id=?", (operation["operation_id"],)
+            )
+            driver = self.service.registry.get(operation["device_id"])
+            self.service.upload_reconciliation.check(
+                raw, driver, driver.device(refresh=True)
+            )
+            self.service.reconcile(operation["operation_id"], acknowledge=True)
+            return self.service.operation(operation["operation_id"])
+        return operation
+
+    def discard(self, asset_id):
+        row = self.db.one("SELECT kind FROM assets WHERE id=?", (asset_id,))
+        meta = self.db.one(
+            "SELECT starred FROM asset_metadata WHERE asset_id=?", (asset_id,)
+        )
+        # Only disposable generated staging files are owned by this recovery.
+        if row and row["kind"] == "cache" and not (meta and meta["starred"]):
+            self.service.assets.path(asset_id).unlink(missing_ok=True)
+            with self.db.transaction() as tx:
+                for table, field in (
+                    ("assets", "id"),
+                    ("asset_sources", "asset_id"),
+                    ("asset_metadata", "asset_id"),
+                ):
+                    tx.execute(f"DELETE FROM {table} WHERE {field}=?", (asset_id,))
+
+    def tick(self, current):
+        for job in self.db.all("SELECT * FROM jobs WHERE enabled=1"):
+            try:
+                self.check(job, current)
+            except FlowError:
+                # A read failure leaves the durable plan in place for a later check.
+                continue
+
+    def check(self, job, current):
+        config = json.loads(job["payload"])
+        if config["source"]["type"] not in (
+            "photo_source",
+            "auto_collage",
+            "template",
+            "provider",
+        ):
+            return
+        plan = self.load(job["id"])
+        if plan and plan["source"] != config["source"]:
+            self.save(job["id"], None)
+            plan = None
+        if not plan:
+            if not job["last_result"] or not job["next_run"]:
+                return
+            operation = self.service.operation(job["last_result"])
+            asset_id = (operation["result"] or {}).get("rendered_asset_id")
+            if operation["status"] not in ("FAILED", "UNKNOWN") or not asset_id:
+                return
+            deadline = datetime.fromisoformat(job["next_run"])
+            remaining = (deadline - current).total_seconds()
+            if remaining <= 0:
+                times = []
+            else:
+                # Five increasing delays occupy the first half of the available
+                # window, leaving time for upload/sync before the next schedule.
+                unit = remaining / 62
+                times = [
+                    (current + timedelta(seconds=unit * n)).isoformat()
+                    for n in (1, 3, 7, 15, 31)
+                ]
+            plan = dict(
+                root=operation["operation_id"],
+                active=operation["operation_id"],
+                asset_id=asset_id,
+                source=config["source"],
+                times=times,
+                count=0,
+                deadline=deadline.isoformat(),
+                phase="extra",
+            )
+            self.save(job["id"], plan)
+        operation = self.service.operation(plan["active"])
+        deadline = min(
+            datetime.fromisoformat(plan["deadline"]),
+            datetime.fromisoformat(job["next_run"]),
+        )
+        if (
+            plan["phase"] == "extra"
+            and current >= deadline
+            and operation["status"] != "COMPLETED"
+        ):
+            if operation["status"] == "SYNCING":
+                self.service.update(
+                    operation["operation_id"],
+                    "UNKNOWN",
+                    operation["result"],
+                    operation["error"],
+                )
+                operation = self.service.operation(operation["operation_id"])
+            operation = self.close_unknown(operation)
+            if operation["status"] == "QUEUED":
+                self.service.update(
+                    operation["operation_id"],
+                    "FAILED",
+                    error={
+                        "code": "CONFLICT",
+                        "message": "Upload retry window closed",
+                        "request_id": operation["request_id"],
+                        "details": {"reason": "RETRY_WINDOW_CLOSED"},
+                    },
+                )
+            if operation["status"] != "COMPLETED":
+                plan["phase"] = "scheduled"
+                self.save(job["id"], plan)
+                return
+        if operation["status"] == "COMPLETED":
+            self.save(job["id"], None)
+            # Extra retries are not job_runs and do not move the next plan time.
+            self.db.execute(
+                "UPDATE jobs SET last_result=? WHERE id=?",
+                (operation["operation_id"], job["id"]),
+            )
+            return
+        if operation["status"] not in ("FAILED", "UNKNOWN"):
+            return
+        if plan["phase"] == "replacement":
+            # A failed replacement gets its own bounded recovery window.
+            self.db.execute(
+                "UPDATE jobs SET last_result=? WHERE id=?",
+                (operation["operation_id"], job["id"]),
+            )
+            self.save(job["id"], None)
+            return
+        if plan["phase"] == "scheduled_running":
+            operation = self.close_unknown(operation)
+            if operation["status"] == "COMPLETED":
+                return
+            self.discard(plan["asset_id"])
+            payload = self.payload(config)
+            key = "replacement-" + plan["root"]
+            op_id = self.service.submit(
+                "display", payload, config["device_id"], "scheduler-retry", key, key
+            )
+            plan.update(phase="replacement", active=op_id)
+            self.save(job["id"], plan)
+            self.db.execute(
+                "UPDATE jobs SET last_result=? WHERE id=?", (op_id, job["id"])
+            )
+            self.db.event(
+                "upload.regenerated",
+                {
+                    "job_id": job["id"],
+                    "operation_id": op_id,
+                    "failed_asset_id": plan["asset_id"],
+                },
+            )
+            return
+        if current >= deadline or plan["count"] >= len(plan["times"]):
+            plan["phase"] = "scheduled"
+            self.save(job["id"], plan)
+            return
+        if current < datetime.fromisoformat(plan["times"][plan["count"]]):
+            return
+        operation = self.close_unknown(operation)
+        if operation["status"] == "COMPLETED":
+            return
+        number = plan["count"] + 1
+        key = f"upload-retry-{plan['root']}-{number}"
+        op_id = self.service.submit(
+            "display",
+            self.reuse(self.payload(config), plan["asset_id"]),
+            config["device_id"],
+            "scheduler-retry",
+            key,
+            key,
+        )
+        plan.update(active=op_id, count=number)
+        self.save(job["id"], plan)
+        self.db.execute("UPDATE jobs SET last_result=? WHERE id=?", (op_id, job["id"]))
+        self.db.event(
+            "upload.retry",
+            {
+                "job_id": job["id"],
+                "operation_id": op_id,
+                "attempt": number,
+                "deadline": deadline.isoformat(),
+            },
+        )
+
+    @staticmethod
+    def payload(config):
+        return {
+            "device_id": config["device_id"],
+            "content": config["source"],
+            "options": {
+                "duration": config["display_duration"],
+                "restore_previous": config["restore_previous"],
+                "priority": config["priority"],
+                "cleanup_unstarred": config.get("cleanup_unstarred", False),
+            },
+        }

pigway_frame_flow/settings.py

@@ -56,6 +56,12 @@ class Settings:
     photo_root: Path = field(
         default_factory=lambda: Path(os.getenv("PHOTO_ROOT", "/photos"))
     )
+    photos_cache_bytes: int = field(
+        default_factory=lambda: max(
+            1024 * 1024,
+            int(os.getenv("SYNOLOGY_PHOTOS_CACHE_BYTES", str(256 * 1024 * 1024))),
+        )
+    )
     max_bytes: int = 20 * 1024 * 1024
     idempotency_hours: int = 168
     sync_timeout: int = 600

pigway_frame_flow/web/app.js

@@ -1,17 +1,23 @@
 'use strict';
 const $=s=>document.querySelector(s);
 const state={lang:localStorage.getItem('ff-language')||'zh',theme:localStorage.getItem('ff-theme')||'system',page:location.hash.slice(1)||'dashboard',token:'',csrf:'',device:'living-room',settings:null,devices:[],templates:[],gallery:[],assets:[],blobs:[],tab:'cloud',preview:null,templatePreview:null,selectedTemplate:null,epoch:0};
-function forgetLogin(){state.galleryCache?.clear();localStorage.removeItem('ff-login');state.token='';state.csrf='';state.settings=null;state.devices=[];state.templates=[];}
-async function loadConnection(){const [settings,devices,templates]=await Promise.all([api('/api/v1/settings'),api('/api/v1/devices').catch(error=>{toast(error.message);return [];}),api('/api/v1/templates')]);state.settings=settings;state.devices=devices;state.templates=templates;state.device=state.devices[0]?.id||state.device;}
+function forgetLogin(){state.galleryQuery='';state.galleryOrder='newest';state.galleryJobsRequest=null;state.galleryCache?.clear();localStorage.removeItem('ff-login');state.token='';state.csrf='';state.settings=null;state.devices=[];state.templates=[];}
+async function loadConnection(){
+ const [settings,templates]=await Promise.all([api('/api/v1/settings'),api('/api/v1/templates')]);
+ const devices=settings.device_catalog||await api('/api/v1/devices').catch(error=>{toast(error.message);return [];});
+ state.settings=settings;state.devices=devices;state.templates=templates;state.device=devices[0]?.id||settings.device_id||state.device;
+ if(settings.device_catalog&&state.page!=='dashboard')void api('/api/v1/devices').then(details=>{if(state.settings!==settings||!state.token)return;state.devices=details;shell();}).catch(error=>{if(state.settings===settings&&state.token)toast(error.message);});
+}
 const icons={dashboard:'◫',gallery:'▧','photo-sources':'▣',upload:'↥',templates:'▦',studio:'▦',automation:'◷',playlists:'▤',history:'↺',connections:'↔',settings:'⚙'};
 const t=k=>window.MESSAGES[state.lang][k]||k;
+function operationErrorMessage(error){const reason=error?.details?.reason;if(reason&&t(reason)!==reason)return t(reason);return error?.code&&t(error.code)!==error.code?t(error.code):(error?.message||t('error'));}
 const esc=v=>String(v??'—').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
 const fmt=v=>v?new Date(v).toLocaleString(state.lang==='zh'?'zh-CN':'en-GB',{timeZone:'Asia/Shanghai'}):'—';
 const padTime=(hour,minute)=>`${String(hour).padStart(2,'0')}:${String(minute).padStart(2,'0')}`;
-function normaliseSchedule(schedule){const copy={...schedule};if(copy.type!=='cron')return copy;const match=/^(\d{1,2})\s+(\d{1,2})\s+\*\s+\*\s+(\*|1-5|6,0|0,6)$/.exec(copy.cron||'');if(!match)return copy;const type=match[3]==='*'?'daily':match[3]==='1-5'?'weekdays':'weekends';return {type,time:padTime(match[2],match[1])};}
-function scheduleTypeLabel(type){if(type!=='cron')return t(type);return state.lang==='zh'?'高级规则（Cron）':'Advanced rule (Cron)';}
-function scheduleSummary(schedule){const value=normaliseSchedule(schedule);if(['daily','weekdays','weekends'].includes(value.type))return `${scheduleTypeLabel(value.type)} · ${value.time}（${state.lang==='zh'?'上海时间':'Shanghai time'}）`;if(value.type==='cron')return `${scheduleTypeLabel('cron')} · ${value.cron}`;return `${scheduleTypeLabel(value.type)} · ${fmt(value.at)}`;}
-function scheduleHint(type){if(type==='cron')return state.lang==='zh'?'仅在需要特殊规则时使用；例如“每天 08:00”请选择“每天”。':'Use only for special rules; choose Daily for a regular time.';if(['date','temporary'].includes(type))return state.lang==='zh'?'选择一次性执行的日期和时间。':'Choose the date and time for this one-time task.';return state.lang==='zh'?'选择执行时间（上海时区）。':'Choose a time in Shanghai time.';}
+function normaliseSchedule(schedule){const copy={...schedule};if(copy.type==='interval')return {type:copy.interval_minutes%60===0?'hours':'minutes',every:copy.interval_minutes%60===0?copy.interval_minutes/60:copy.interval_minutes};if(copy.type!=='cron')return copy;const match=/^(\d{1,2})\s+(\d{1,2})\s+\*\s+\*\s+(\*|1-5|6,0|0,6)$/.exec(copy.cron||'');if(!match)return copy;const type=match[3]==='*'?'daily':match[3]==='1-5'?'weekdays':'weekends';return {type,time:padTime(match[2],match[1])};}
+function scheduleTypeLabel(type){if(type==='hours')return state.lang==='zh'?'每隔若干小时':'Every N hours';if(type==='minutes')return state.lang==='zh'?'每隔若干分钟':'Every N minutes';if(type!=='cron')return t(type);return state.lang==='zh'?'高级规则（Cron）':'Advanced rule (Cron)';}
+function scheduleSummary(schedule){const value=normaliseSchedule(schedule);if(['hours','minutes'].includes(value.type))return state.lang==='zh'?`每 ${value.every} ${value.type==='hours'?'小时':'分钟'}`:`Every ${value.every} ${value.type}`;if(['daily','weekdays','weekends'].includes(value.type))return `${scheduleTypeLabel(value.type)} · ${value.time}（${state.lang==='zh'?'上海时间':'Shanghai time'}）`;if(value.type==='cron')return `${scheduleTypeLabel('cron')} · ${value.cron}`;return `${scheduleTypeLabel(value.type)} · ${fmt(value.at)}`;}
+function scheduleHint(type){if(['hours','minutes'].includes(type))return state.lang==='zh'?'从保存起等待一个间隔后首次执行，此后按间隔重复；不是图片显示时长。':'First runs one interval after saving, then repeats. This is separate from display duration.';if(type==='cron')return state.lang==='zh'?'仅在需要特殊规则时使用；例如“每天 08:00”请选择“每天”。':'Use only for special rules; choose Daily for a regular time.';if(['date','temporary'].includes(type))return state.lang==='zh'?'选择一次性执行的日期和时间。':'Choose the date and time for this one-time task.';return state.lang==='zh'?'选择执行时间（上海时区）。':'Choose a time in Shanghai time.';}
 const buttons=(id,text,primary=false)=>`<button type="button" id="${id}" class="${primary?'primary':''}">${t(text)}</button>`;
 let toastTimer;
 function toast(message){$('#toast').textContent=message;$('#toast').style.display='block';clearTimeout(toastTimer);toastTimer=setTimeout(()=>$('#toast').style.display='none',6000);}
@@ -20,7 +26,7 @@ async function api(path,options={}){
  if(options.body&&!(options.body instanceof FormData)){headers['Content-Type']='application/json';options.body=JSON.stringify(options.body);}
  const response=await fetch(path,{...options,headers});
  if(!response.ok){let error;try{error=(await response.json()).error;}catch{}if(response.status===401&&error?.code!=='OFFICIAL_AUTH_REQUIRED')forgetLogin();
- const e=new Error((error?.code||response.status)+': '+(error?.code&&t(error.code)!==error.code?t(error.code):(error?.message||t('error'))));e.code=error?.code;throw e;}
+ const e=new Error((error?.code||response.status)+': '+operationErrorMessage(error));e.code=error?.code;throw e;}
  if(response.status===204)return null;
  return options.binary?await response.blob():await response.json();
 }
@@ -29,7 +35,12 @@ function busy(fn){return async event=>{try{await fn(event);}catch(e){toast(e.mes
 function applyTheme(){const dark=state.theme==='dark'||(state.theme==='system'&&matchMedia('(prefers-color-scheme:dark)').matches);document.documentElement.dataset.theme=dark?'dark':'light';}
 function revealCurrentNavigation(){const active=$('#nav .active'),sidebar=$('.sidebar');if(active&&matchMedia('(max-width:720px)').matches)sidebar.scrollLeft=active.offsetLeft-(sidebar.clientWidth-active.offsetWidth)/2;}
 window.addEventListener('resize',revealCurrentNavigation);
-function shell(){document.documentElement.lang=state.lang==='zh'?'zh-CN':'en';$('#lang').textContent=state.lang==='zh'?'EN':'中文';$('#theme').title=t('theme');$('#nav').innerHTML=Object.entries(icons).map(([id,icon])=>`<button data-page="${id}" class="${id===state.page?'active':''}" ${id===state.page?'aria-current="page"':''}><span class="nav-icon">${icon}</span><span>${t(id)}</span></button>`).join('');document.querySelectorAll('[data-page]').forEach(b=>b.onclick=()=>navigate(b.dataset.page));$('#page-title').textContent=t(state.page);$('#device').innerHTML=(state.devices.length?state.devices:[{id:state.device,name:state.device}]).map(d=>`<option value="${esc(d.id)}" ${d.id===state.device?'selected':''}>${esc(d.name)}</option>`).join('');revealCurrentNavigation();}
+function deviceNameForId(id){return deviceDisplayName(state.devices.find(d=>d.id===id)||{id,name:id});}
+function operationActionLabel(action){const labels={'render':['生成预览','Generate preview'],'render-ai':['AI 生成图片','Generate AI image'],'official-widget':['更新官方订阅','Update official widget'],'delete':['删除图片','Delete image'],'display':['显示图片','Display image'],'restore':['恢复图片','Restore image'],'local-upload':['保存到图库','Save to gallery'],'reconcile':['核对状态','Reconcile']};return labels[action]?.[state.lang==='zh'?0:1]||t('operation');}
+function operationClientLabel(client){return client==='admin'?tr('管理员','Administrator'):client==='scheduler'?tr('自动调度','Scheduler'):client;}
+function operationErrorLabel(error){if(!error?.code)return '';const label=t(error.code);return label===error.code?t('error'):label;}
+function deviceDisplayName(device){const name=device.name||device.id;return device.id==='living-room'&&['living-room','Living room'].includes(name)?t('livingRoom'):name;}
+function shell(){document.documentElement.lang=state.lang==='zh'?'zh-CN':'en';$('#lang').textContent=state.lang==='zh'?'EN':'中文';$('#theme').title=t('theme');$('#nav').innerHTML=Object.entries(icons).map(([id,icon])=>`<button data-page="${id}" class="${id===state.page?'active':''}" ${id===state.page?'aria-current="page"':''}><span class="nav-icon">${icon}</span><span>${t(id)}</span></button>`).join('');document.querySelectorAll('[data-page]').forEach(b=>b.onclick=()=>navigate(b.dataset.page));$('#page-title').textContent=t(state.page);$('#device').innerHTML=(state.devices.length?state.devices:[{id:state.device,name:state.device}]).map(d=>`<option value="${esc(d.id)}" ${d.id===state.device?'selected':''}>${esc(deviceDisplayName(d))}</option>`).join('');revealCurrentNavigation();}
 // A destination appears only when its connection and read/write adapter are available.
 // Future cloud-drive destinations must implement their adapter before registration here.
 const galleryDestinationAdapters=new Set(['kokonna','local-assets']);
@@ -62,17 +73,17 @@ async function blobImage(img,path){
 }
 function hydrateImages(){const observer=new IntersectionObserver(entries=>entries.forEach(entry=>{if(entry.isIntersecting){observer.unobserve(entry.target);blobImage(entry.target,entry.target.dataset.src);}}),{rootMargin:'100px'});document.querySelectorAll('img[data-src]').forEach(img=>{imageLoading(img);observer.observe(img);});}
 function notice(){return state.settings?.mock?`<div class="notice">${t('mock')}</div>`:'';}
-async function navigate(page=state.page){const previousPage=state.page;state.page=icons[page]?page:'dashboard';location.hash=state.page;shell();state.epoch++;const epoch=state.epoch;
+async function navigate(page=state.page){document.body.classList.toggle('login-mode',!state.token);const previousPage=state.page;state.page=icons[page]?page:'dashboard';location.hash=state.page;shell();state.epoch++;const epoch=state.epoch;
  if(!state.token){login();return;}
  if(previousPage!==state.page)$('#main').replaceChildren();
  const previousBlobs=state.blobs;state.blobs=[];
  try{await views[state.page](epoch);for(const url of previousBlobs)URL.revokeObjectURL(url);if(epoch!==state.epoch)return;const enhance={dashboard:enhanceDashboard,templates:enhanceTemplates,settings:enhanceSettings,upload:enhanceUpload,history:enhanceHistory,automation:enhanceAutomation}[state.page];if(enhance)await enhance();guardDeviceButtons();}catch(e){if(epoch!==state.epoch)return;if(!state.token){shell();login();toast(e.message);return;}$('#main').innerHTML=`<div class="card empty"><strong>${t('apiError')}</strong><p>${esc(e.message)}</p>${buttons('retry','refresh')}</div>`;bind('retry',()=>navigate());}
 }
-function login(){ $('#main').innerHTML=`<div class="card" style="max-width:560px;margin:40px auto"><span class="badge">FRAME FLOW</span><h2 style="margin-top:20px">${t('connect')}</h2><p class="hint">${t('tokenHint')}</p><form id="login-form"><div class="field"><label for="username">${t('username')}</label><input id="username" required autocomplete="username"></div><div class="field"><label for="password">${t('password')}</label><input id="password" type="password" required autocomplete="current-password"></div><label class="check-row"><input id="remember-login" type="checkbox" checked>${t('rememberLogin')}</label><button class="primary" type="submit">${t('connect')}</button></form></div>`;$('#login-form').onsubmit=busy(async e=>{e.preventDefault();try{const account=await api('/api/v1/auth/login',{method:'POST',body:{username:$('#username').value.trim(),password:$('#password').value,remember:$('#remember-login').checked}});state.token=account.username;state.csrf=account.csrf_token;await loadConnection();await navigate();}catch(error){forgetLogin();shell();login();toast(error.message);}});}
+function login(){document.body.classList.add('login-mode');$('#page-title').textContent=t('signIn');$('#main').innerHTML=`<section class="card login-card" aria-labelledby="login-title"><span class="badge">FRAME FLOW</span><h2 id="login-title">${t('connect')}</h2><p class="hint">${t('tokenHint')}</p><form id="login-form"><div class="field"><label for="username">${t('username')}</label><input id="username" required autocomplete="username"></div><div class="field"><label for="password">${t('password')}</label><input id="password" type="password" required autocomplete="current-password"></div><label class="check-row"><input id="remember-login" type="checkbox" checked><span>${t('rememberLogin')}</span></label><button class="primary" type="submit">${t('connect')}</button></form></section>`;$('#login-form').onsubmit=busy(async e=>{e.preventDefault();try{const account=await api('/api/v1/auth/login',{method:'POST',body:{username:$('#username').value.trim(),password:$('#password').value,remember:$('#remember-login').checked}});state.token=account.username;state.csrf=account.csrf_token;await loadConnection();await navigate();}catch(error){forgetLogin();shell();login();toast(error.message);}});}
 // LAN HTTP is not a secure context; getRandomValues remains available there.
 function clientUUID(){if(typeof crypto.randomUUID==='function')return crypto.randomUUID();const bytes=crypto.getRandomValues(new Uint8Array(16));bytes[6]=(bytes[6]&15)|64;bytes[8]=(bytes[8]&63)|128;const hex=Array.from(bytes,b=>b.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)}`;}
 async function accepted(path,payload){const key='web-'+clientUUID();const result=await api(path,{method:'POST',body:payload,headers:{'Idempotency-Key':key}});toast(t('accepted'));return result.operation_id;}
-async function waitOperation(id){for(let n=0;n<120;n++){const operation=await api('/api/v1/operations/'+id);if(operation.status==='COMPLETED')return operation;if(['FAILED','UNKNOWN'].includes(operation.status))throw new Error(operation.status==='UNKNOWN'?t('unknown'):(operation.error?.message||t('error')));await new Promise(resolve=>setTimeout(resolve,2000));}throw new Error(t('syncing'));}
+async function waitOperation(id){for(let n=0;n<120;n++){const operation=await api('/api/v1/operations/'+id);if(operation.status==='COMPLETED')return operation;if(['FAILED','UNKNOWN'].includes(operation.status))throw new Error(operation.status==='UNKNOWN'?t('unknown'):operationErrorMessage(operation.error));await new Promise(resolve=>setTimeout(resolve,2000));}throw new Error(t('syncing'));}
 function showModal(html){
  const dialog=$('#modal'),content=$('#modal-content');content.innerHTML=html;
  const image=content.querySelector('img');dialog.classList.toggle('image-viewer',!!image);document.body.classList.toggle('image-viewer-open',!!image);dialog.onclose=()=>document.body.classList.remove('image-viewer-open');
@@ -90,6 +101,7 @@ function showModal(html){
  }
  dialog.showModal();bind('modal-cancel',()=>dialog.close());
 }
+async function openImageViewer(path,name){showModal(`<h2>${esc(name)}</h2><img id="original-image" class="preview" alt="${esc(name)}"><div class="modal-actions">${buttons('modal-cancel','cancel')}</div>`);await blobImage($('#original-image'),path);}
 async function confirmDialog(message,fn){showModal(`<h2>${t('confirm')}</h2><p>${esc(message)}</p><div class="modal-actions">${buttons('modal-cancel','cancel')}${buttons('modal-confirm','confirm',true)}</div>`);bind('modal-confirm',async()=>{await fn();$('#modal').close();});}
 function detail(label,value){return `<div><small>${t(label)}</small><strong>${esc(value)}</strong></div>`;}
 function liveWriteAllowed(){return state.settings?.mock||state.settings?.write_enabled;}
@@ -106,34 +118,38 @@ async function templateEditor(selected){
  const reset=document.createElement('button');reset.id='reset-template';reset.textContent=t('resetTemplate');$('#save-template').after(reset);bind('reset-template',()=>confirmDialog(t('resetConfirm'),async()=>{await api('/api/v1/templates/'+selected.id+'/config',{method:'DELETE'});await navigate();}));
  const save=$('#save-template');const oldSave=save.onclick;save.onclick=async e=>{if([...panel.querySelectorAll('textarea'),raw].some(x=>!x.checkValidity())){toast(t('INVALID_REQUEST'));return;}await oldSave(e);};
 }
-function accountSettings(){const section=$('#logout').parentElement;const form=document.createElement('form');form.id='password-form';form.innerHTML=`<h3>${t('changePassword')}</h3><div class="field"><label for="current-password">${t('currentPassword')}</label><input id="current-password" type="password" required autocomplete="current-password"></div><div class="field"><label for="new-password">${t('newPassword')}</label><input id="new-password" type="password" minlength="8" required autocomplete="new-password"></div><button type="submit">${t('changePassword')}</button>`;section.append(form);form.onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/auth/password',{method:'PUT',body:{current_password:$('#current-password').value,new_password:$('#new-password').value}});forgetLogin();shell();login();toast(t('passwordChanged'));});}
+function accountSettings(){const section=$('#logout').parentElement;const form=document.createElement('form');form.id='password-form';form.innerHTML=`<h3>${t('changePassword')}</h3><div class="form-grid password-fields"><div class="field"><label for="current-password">${t('currentPassword')}</label><input id="current-password" type="password" required autocomplete="current-password"></div><div class="field"><label for="new-password">${t('newPassword')}</label><input id="new-password" type="password" minlength="8" required autocomplete="new-password"></div></div><button type="submit">${t('changePassword')}</button>`;section.append(form);form.onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/auth/password',{method:'PUT',body:{current_password:$('#current-password').value,new_password:$('#new-password').value}});forgetLogin();shell();login();toast(t('passwordChanged'));});}
 const views={
  studio:()=>layoutStudioPage(),
  connections:()=>connectionsPage(),
  'photo-sources':async()=>{ $('#main').innerHTML='';await photoSourcesPanel(); },
- async dashboard(epoch){const d=await api('/api/v1/devices/'+state.device);if(epoch!==state.epoch)return;const s=d.slideshow;$('#main').innerHTML=notice()+`${d.power.battery_percent!==null&&d.power.battery_percent<20?`<div class="notice warning">${t('lowBattery')}</div>`:''}<section class="card hero"><div class="hero-info"><span class="badge ${d.status==='offline'?'bad':''}">● ${t(d.status).toUpperCase()}</span><h2>${esc(d.name)}</h2><p>${esc(d.model)} · ${esc(d.model_code)} · ${d.display.width} × ${d.display.height}</p><div class="actions">${buttons('go-upload','upload',true)}${buttons('restore','restore')}${buttons('refresh-device','refresh')}</div><p class="hint" style="margin-top:28px">${t('refreshInterval')}</p></div><div class="frame-demo"></div></section><div class="stats">${[['battery',d.power.battery_percent===null?'—':d.power.battery_percent+'%'],['current',d.current_content.id??'—'],['sync',t(d.current_content.synced?'synced':'syncing')],['firmware',d.firmware]].map(([l,v])=>`<div class="card stat"><div class="label">${t(l)}</div><div class="value">${esc(v)}</div></div>`).join('')}</div><div class="columns"><section class="card"><h3>${t('device')}</h3><div class="detail-grid">${detail('heartbeat',fmt(d.last_seen_at))}${detail('rotation',d.display.rotation+'°')}${detail('timezone',d.timezone)}${detail('coverId',d.current_content.cover_id??'—')}${detail('storage',d.storage_used_bytes===null?'—':(d.storage_used_bytes/1024/1024).toFixed(1)+' MiB')}${detail('model',t(d.model_verified?'modelVerified':'modelConfigured'))}</div></section><section class="card"><h3>${t('cloudRotation')}</h3><div class="detail-grid">${detail('mode',s.mode?t(s.mode):'—')}${detail('interval',s.interval_minutes==null?'—':s.interval_minutes+' '+t('minutes'))}</div><p class="hint">${t('rotationNotice')}</p><a href="#playlists" id="go-playlists">${t('playlists')} →</a></section></div>`;bind('go-upload',()=>navigate('upload'));bind('refresh-device',async()=>{await api('/api/v1/devices/'+state.device+'?refresh=true');await navigate();});$('#restore').disabled=!d.can_restore;bind('restore',()=>accepted('/api/v1/devices/'+state.device+'/restore',{}));$('#go-playlists').onclick=e=>{e.preventDefault();navigate('playlists');};},
+ async dashboard(epoch){const d=await api('/api/v1/devices/'+state.device);if(epoch!==state.epoch)return;state.devices=state.devices.map(x=>x.id===d.id?{...x,name:d.name}:x);shell();const s=d.slideshow;$('#main').innerHTML=notice()+`${d.power.battery_percent!==null&&d.power.battery_percent<20?`<div class="notice warning">${t('lowBattery')}</div>`:''}<section class="card hero"><div class="hero-info"><span class="badge ${d.status==='offline'?'bad':''}">● ${t(d.status).toUpperCase()}</span><h2>${esc(d.name)}</h2><p>${esc(d.model)} · ${esc(d.model_code)} · ${d.display.width} × ${d.display.height}</p><div class="actions">${buttons('go-upload','upload',true)}${buttons('restore','restore')}${buttons('refresh-device','refresh')}</div><p class="hint" style="margin-top:28px">${t('refreshInterval')}</p></div><div class="frame-demo"></div></section><div class="stats">${[['battery',d.power.battery_percent===null?'—':d.power.battery_percent+'%'],['currentImageId',d.current_content.id??'—'],['sync',t(d.current_content.synced?'synced':'syncing')],['firmware',d.firmware]].map(([l,v])=>`<div class="card stat"><div class="label">${t(l)}</div><div class="value">${esc(v)}</div></div>`).join('')}</div><div class="columns"><section class="card"><h3>${t('device')}</h3><div class="detail-grid">${detail('heartbeat',fmt(d.last_seen_at))}${detail('rotation',d.display.rotation+'°')}${detail('timezone',d.timezone)}${detail('coverId',d.current_content.cover_id??'—')}${detail('storage',d.storage_used_bytes===null?'—':(d.storage_used_bytes/1024/1024).toFixed(1)+' MiB')}${detail('modelSource',t(d.model_verified?'modelVerified':'modelConfigured'))}</div></section><section class="card"><h3>${t('cloudRotation')}</h3><div class="detail-grid">${detail('playbackMode',s.mode?t(s.mode):'—')}${detail('switchInterval',s.interval_minutes==null?'—':s.interval_minutes+' '+t('minutes'))}</div><p class="hint">${t('rotationNotice')}</p><a href="#playlists" id="go-playlists">${t('playlists')} →</a></section></div>`;bind('go-upload',()=>navigate('upload'));bind('refresh-device',async()=>{await api('/api/v1/devices/'+state.device+'?refresh=true');await navigate();});$('#restore').disabled=!d.can_restore;bind('restore',()=>accepted('/api/v1/devices/'+state.device+'/restore',{}));$('#go-playlists').onclick=e=>{e.preventDefault();navigate('playlists');};},
  async gallery(epoch){
  const destinations=galleryDestinations();if(!destinations.some(d=>d.id===state.tab))state.tab=destinations[0]?.id||'local';
  const key=JSON.stringify([state.device,state.tab,state.assetOffset||0,state.assetOrigin||'all',state.assetJob||'']);
  const cache=state.galleryCache||(state.galleryCache=new Map());const cached=cache.get(key);
- const render=items=>{if(epoch!==state.epoch)return;state.gallery=items;$('#main').innerHTML=notice()+`<div class="section-heading"><div class="tabs gallery-tabs">${destinations.map(d=>`<button id="${esc(d.id)}-tab" data-gallery-destination="${esc(d.id)}" class="${state.tab===d.id?'active':''}">${esc(galleryDestinationName(d))}</button>`).join('')}</div><div class="actions">${buttons('gallery-refresh','refresh')}${state.tab==='cloud'?buttons('show-name','displayByName'):''}${buttons('gallery-upload','upload',true)}</div></div>${state.tab==='local'?`<div class="notice">${t('uploadNotice')}</div>`:''}${items.length?`<div class="gallery">${items.map((x,i)=>`<article class="card image-card"><img class="thumb" alt="${esc(x.name)}" data-src="${esc(x.url+(state.tab==='cloud'?'?thumbnail=true':''))}"><h3 title="${esc(x.name)}">${esc(x.name)}</h3><small>${state.tab==='cloud'?'#'+x.image_id:'LOCAL'} · ${esc(fmt(x.created_at))}</small><div class="actions"><button class="primary" data-show="${i}" ${x.current?'disabled':''}>${t(x.current?'current':'display')}</button><button data-original="${i}">${t('original')}</button><button class="danger" data-delete="${i}">${t('delete')}</button></div></article>`).join('')}</div>`:`<div class="card empty"><strong>${t('noImages')}</strong>${t('emptyHint')}</div>`}`;bind('cloud-tab',()=>{state.tab='cloud';return navigate();});bind('local-tab',()=>{state.tab='local';return navigate();});bind('gallery-refresh',()=>navigate());bind('gallery-upload',()=>navigate('upload'));bind('show-name',()=>{showModal(`<h2>${t('displayByName')}</h2><div class="field"><label for="image-name">${t('name')}</label><input id="image-name" maxlength="120"></div><div class="modal-actions">${buttons('modal-cancel','cancel')}${buttons('show-name-confirm','display',true)}</div>`);bind('show-name-confirm',async()=>{const name=$('#image-name').value;$('#modal').close();displayDialog({type:'image',image_name:name});});});enhanceGallery();guardDeviceButtons();hydrateImages();document.querySelectorAll('[data-show]').forEach(b=>b.onclick=busy(()=>{const x=items[b.dataset.show];if(x.current)return;return displayDialog(state.tab==='cloud'?{type:'image',image_id:x.image_id}:{type:'image',asset_id:x.asset_id});}));document.querySelectorAll('[data-original]').forEach(b=>b.onclick=busy(async()=>{const x=items[b.dataset.original];showModal(`<h2>${esc(x.name)}</h2><img id="original-image" class="preview" alt="${esc(x.name)}"><div class="modal-actions">${buttons('modal-cancel','cancel')}</div>`);await blobImage($('#original-image'),x.url);}));document.querySelectorAll('[data-delete]').forEach(b=>b.onclick=()=>{const x=items[b.dataset.delete];confirmDialog(x.current?t('deleteCurrent'):t('deleteConfirm'),async()=>{if(state.tab==='local'){await api('/api/v1/assets/'+x.asset_id,{method:'DELETE'});}else{const result=await api(`/api/v1/devices/${state.device}/images/${x.image_id}?confirm_current=${x.current}`,{method:'DELETE',headers:{'Idempotency-Key':'web-'+clientUUID()}});await waitOperation(result.operation_id);}await navigate();});});};
- if(cached)render(cached);
+ const render=(items,pending=false)=>{if(epoch!==state.epoch)return;state.gallery=items;$('#main').innerHTML=notice()+`<div class="section-heading"><div class="tabs gallery-tabs">${destinations.map(d=>`<button id="${esc(d.id)}-tab" data-gallery-destination="${esc(d.id)}" class="${state.tab===d.id?'active':''}">${esc(galleryDestinationName(d))}</button>`).join('')}</div><div class="actions">${buttons('gallery-refresh','refresh')}${state.tab==='cloud'?buttons('show-name','displayByName'):''}${buttons('gallery-upload','upload',true)}<span id="gallery-list-status" class="hint" role="status" ${pending?'':'hidden'}>${pending?t('galleryListLoading'):''}</span></div></div>${state.tab==='local'?`<div class="notice">${t('uploadNotice')}</div>`:''}${`<div class="gallery" aria-busy="${pending}">${items.map((x,i)=>`<article class="card image-card"><button class="image-preview" data-original="${i}" aria-label="${t('original')} · ${esc(x.name)}"><img class="thumb" alt="${esc(x.name)}" data-src="${esc(x.url+(state.tab==='cloud'?'?thumbnail=true':''))}"></button><h3 class="${state.tab==='local'?'source-path':''}" title="${esc(x.source_path||x.name)}">${esc(state.tab==='local'?(x.source_path||x.name):x.name)}</h3><small>${state.tab==='cloud'?'#'+x.image_id:t('local')} · ${esc(fmt(x.created_at))}</small><div class="actions"><button class="primary" data-show="${i}" ${x.current?'disabled':''}>${t(x.current?'current':'display')}</button><button class="danger" data-delete="${i}">${t('delete')}</button></div></article>`).join('')}</div>`}${!pending&&!items.length?`<div class="card empty"><strong>${t('noImages')}</strong>${t('emptyHint')}</div>`:''}`;bind('cloud-tab',()=>{state.tab='cloud';return navigate();});bind('local-tab',()=>{state.tab='local';return navigate();});bind('gallery-refresh',()=>navigate());bind('gallery-upload',()=>navigate('upload'));bind('show-name',()=>{showModal(`<h2>${t('displayByName')}</h2><div class="field"><label for="image-name">${t('name')}</label><input id="image-name" maxlength="120"></div><div class="modal-actions">${buttons('modal-cancel','cancel')}${buttons('show-name-confirm','display',true)}</div>`);bind('show-name-confirm',async()=>{const name=$('#image-name').value;$('#modal').close();displayDialog({type:'image',image_name:name});});});enhanceGallery();guardDeviceButtons();hydrateImages();document.querySelectorAll('[data-show]').forEach(b=>b.onclick=busy(()=>{const x=items[b.dataset.show];if(x.current)return;return displayDialog(state.tab==='cloud'?{type:'image',image_id:x.image_id}:{type:'image',asset_id:x.asset_id});}));document.querySelectorAll('[data-original]').forEach(b=>b.onclick=busy(async()=>{const x=items[b.dataset.original];await openImageViewer(x.url,x.name);}));document.querySelectorAll('[data-delete]').forEach(b=>b.onclick=()=>{const x=items[b.dataset.delete];confirmDialog(state.tab==='local'?t('localDeleteConfirm'):x.current?t('deleteCurrent'):t('cloudDeleteConfirm'),async()=>{if(state.tab==='local'){await api('/api/v1/assets/'+x.asset_id,{method:'DELETE'});}else{const result=await api(`/api/v1/devices/${state.device}/images/${x.image_id}?confirm_current=${x.current}`,{method:'DELETE',headers:{'Idempotency-Key':'web-'+clientUUID()}});await waitOperation(result.operation_id);}await navigate();});});};
+ render(cached||[],!cached);
+ try{
  const items=state.tab==='cloud'?await api('/api/v1/devices/'+state.device+'/images'):await api('/api/v1/assets?limit=200&offset='+(state.assetOffset||0)+'&origin='+encodeURIComponent(state.assetOrigin||'all')+(state.assetJob?'&job_id='+encodeURIComponent(state.assetJob):''));
  if(epoch!==state.epoch)return;cache.set(key,items);
  if(!cached||JSON.stringify(cached)!==JSON.stringify(items))render(items);
+ }catch(error){
+  if(epoch!==state.epoch)return;if(!state.token)throw error;
+  const status=$('#gallery-list-status');status.hidden=false;status.setAttribute('role','alert');status.textContent=error.message;
+  $('.gallery')?.setAttribute('aria-busy','false');
+ }
  },
  async upload(){state.preview=null;$('#main').innerHTML=notice()+`<div class="notice">${t('uploadNotice')}</div><div class="columns"><section class="card"><h2>${t('upload')}</h2><div class="dropzone"><strong>${t('selectFile')}</strong><p class="hint">${t('uploadHint')}</p><input id="file" type="file" accept="image/jpeg,image/png,image/webp" aria-label="${t('selectFile')}"></div><div class="form-grid" style="margin-top:24px"><div class="field"><label for="fit">${t('mode')}</label><select id="fit">${['contain','cover','smart'].map(x=>`<option value="${x}">${t(x)}</option>`).join('')}</select></div><div class="field"><label for="profile">${t('profile')}</label><select id="profile">${['color','grayscale'].map(x=>`<option value="${x}">${t(x)}</option>`).join('')}</select></div></div>${buttons('make-preview','preview',true)}<p class="hint">${t('previewHint')}</p></section><section class="card"><h3>${t('preview')}</h3><div id="preview-box" class="empty">${t('previewHint')}</div><div class="actions" style="margin-top:18px"><button id="save-local" disabled>${t('staging')}</button><button id="display-upload" class="primary" disabled>${t('display')}</button></div></section></div>`;bind('make-preview',async()=>{const file=$('#file').files[0];if(!file)throw new Error(t('selectFile'));const form=new FormData();form.append('file',file);form.append('fit',$('#fit').value);form.append('profile',$('#profile').value);state.preview=await api('/api/v1/preview',{method:'POST',body:form});$('#preview-box').className='';$('#preview-box').innerHTML='<img id="upload-preview" class="preview" alt="Preview">';await blobImage($('#upload-preview'),state.preview.url);$('#save-local').disabled=false;$('#display-upload').disabled=!liveWriteAllowed();});for(const id of ['file','fit','profile'])$('#'+id).onchange=()=>{state.preview=null;$('#save-local').disabled=true;$('#display-upload').disabled=true;};bind('save-local',async()=>{const id=await accepted('/api/v1/devices/'+state.device+'/upload',{type:'image',asset_id:state.preview.asset_id});await waitOperation(id);state.tab='local';return navigate('gallery');});bind('display-upload',()=>displayDialog({type:'image',asset_id:state.preview.asset_id}));},
  async templates(){state.templates=await api('/api/v1/templates');const selected=state.templates.find(x=>x.id===state.selectedTemplate)||state.templates[0];state.selectedTemplate=selected.id;if(state.pendingTemplateData?.template===selected.id){selected.defaults=state.pendingTemplateData.data;state.initialProfile=state.pendingTemplateData.profile;state.pendingTemplateData=null;}state.templatePreview=null;$('#main').innerHTML=notice()+`<div class="notice">${t('templateHint')}<p>${t('templateSteps')}</p></div><div class="template-grid">${state.templates.map((x,i)=>`<div class="card template-card ${x.id===selected.id?'selected':''}" role="button" tabindex="0" data-template="${x.id}"><span>${{'daily-poetry':'詩','calendar':'▦','daily-dashboard':'☀','photo-text':'▣','quote':'❝','system-alert':'◒','weather':'☁'}[x.id]||'▦'}</span><div><h3>${esc(x.name.split(' / ')[state.lang==='zh'?1:0]||x.name)}</h3><small>1200 × 1600 · ${esc(x.id)}</small></div></div>`).join('')}</div><div class="columns"><section class="card"><h3>${t('templateData')}</h3><p class="hint">${t('templateGuideTitle')}</p><p class="hint">${t({'photo-text':'guidePhotoText','daily-dashboard':'guideDashboard',weather:'guideWeather',calendar:'guideCalendar',quote:'guideQuote','daily-poetry':'guidePoetry','system-alert':'guideAlert'}[selected.id]||'templateContentHelp')}</p>${['weather','daily-dashboard'].includes(selected.id)?`<p class="hint">${t('templateWeatherHelp')}</p>`:''}<textarea id="template-data" aria-label="${t('templateData')}">${esc(JSON.stringify(selected.defaults,null,2))}</textarea><div class="field" style="margin-top:16px"><label for="template-profile">${t('profile')}</label><select id="template-profile"><option value="color">${t('color')}</option><option value="grayscale">${t('grayscale')}</option></select><p class="hint">${t('helpProfile')}</p></div><p class="hint">${t('templateActionHelp')}</p><p class="hint">${t('templateAutomationHelp')}</p><div class="actions">${buttons('render-template','render',true)}${buttons('save-template','saveTemplate')}</div></section><section class="card"><h3>${t('preview')}</h3><div id="template-preview" class="empty">${t('templatePreviewHint')}</div><button id="display-template" class="primary" style="margin-top:18px" disabled>${t('display')}</button></section></div>`;document.querySelectorAll('[data-template]').forEach(b=>{b.onclick=()=>{state.selectedTemplate=b.dataset.template;navigate(['collage','poster'].includes(b.dataset.template)?'studio':undefined);};b.onkeydown=e=>{if(e.key==='Enter')b.click();};});bind('render-template',async()=>{const content={type:'template',template:selected.id,data:JSON.parse($('#template-data').value),profile:$('#template-profile').value};if([...document.querySelectorAll('#template-fields textarea'),$('#template-data')].some(x=>!x.checkValidity())){toast(t('INVALID_REQUEST'));return;}const id=await accepted('/api/v1/render',content);$('#template-preview').textContent=t('previewLoading');const op=await waitOperation(id);state.templatePreview=op.result.asset_id;$('#template-preview').className='';$('#template-preview').innerHTML='<img id="template-image" class="preview" alt="Template preview">';await blobImage($('#template-image'),op.result.url);$('#display-template').disabled=!liveWriteAllowed();});bind('save-template',async()=>{await api('/api/v1/templates/'+selected.id+'/config',{method:'PUT',body:{data:JSON.parse($('#template-data').value)}});toast(t('done'));});$('#template-data').oninput=()=>$('#display-template').disabled=true;$('#template-profile').onchange=()=>$('#display-template').disabled=true;bind('display-template',()=>displayDialog({type:'image',asset_id:state.templatePreview}));await templateEditor(selected);if(state.initialProfile){$('#template-profile').value=state.initialProfile;state.initialProfile=null;}},
- async automation(epoch){const jobs=await api('/api/v1/jobs');if(epoch!==state.epoch)return;$('#main').innerHTML=notice()+`<div class="section-heading"><p class="hint">Asia/Shanghai · ${t('automation')}</p>${buttons('new-job','newJob',true)}</div><div class="card">${jobs.length?`<div class="table-wrap"><table><thead><tr>${['name','schedule','status','nextRun','lastRun','result','action'].map(x=>`<th>${t(x)}</th>`).join('')}</tr></thead><tbody>${jobs.map((j,i)=>`<tr><td><strong>${esc(j.name)}</strong><br><small>${esc(j.device_id)}</small></td><td>${t(j.schedule.type)}<br>${esc(j.schedule.time||j.schedule.cron||fmt(j.schedule.at))}</td><td><span class="badge">${t(j.enabled?'enabled':'disabled')}</span></td><td>${fmt(j.next_run)}</td><td>${fmt(j.last_run)}</td><td><code>${esc(j.last_result)}</code></td><td><div class="row-actions"><button data-job-edit="${i}">${t('edit')}</button><button data-job-toggle="${i}">${t(j.enabled?'disabled':'enabled')}</button><button class="danger" data-job-delete="${i}">${t('remove')}</button></div></td></tr>`).join('')}</tbody></table></div>`:`<div class="empty"><strong>${t('noTasks')}</strong></div>`}</div>`;bind('new-job',()=>jobEditor());document.querySelectorAll('[data-job-edit]').forEach(b=>b.onclick=()=>jobEditor(jobs[b.dataset.jobEdit]));document.querySelectorAll('[data-job-toggle]').forEach(b=>b.onclick=busy(async()=>{const j=jobs[b.dataset.jobToggle];await api('/api/v1/jobs/'+j.id,{method:'PUT',body:jobPayload(j,{enabled:!j.enabled})});await navigate();}));document.querySelectorAll('[data-job-delete]').forEach(b=>b.onclick=()=>confirmDialog(t('removeConfirm'),async()=>{await api('/api/v1/jobs/'+jobs[b.dataset.jobDelete].id,{method:'DELETE'});await navigate();}));},
  async playlists(epoch){const playlists=await api('/api/v1/playlists');if(epoch!==state.epoch)return;$('#main').innerHTML=notice()+`<div class="notice">${t('playlistNotice')}</div><div class="section-heading"><h2>${t('playlists')}</h2>${buttons('new-playlist','newPlaylist',true)}</div><div class="gallery">${playlists.map((p,i)=>`<section class="card"><span class="badge">${t(p.enabled?'enabled':'disabled')}</span><h3 style="margin-top:16px">${esc(p.name)}</h3><p class="hint">${p.image_ids.length} ${t('count')} · ${p.interval_minutes} ${t('minutes')} · ${t(p.mode)}</p><p><code>${esc(p.image_ids.join(' → '))}</code></p><small>${t('lastScheduled')}: ${p.position>=0?esc(p.image_ids[p.position]):'—'}</small><div class="actions" style="margin-top:16px"><button data-pl-edit="${i}">${t('edit')}</button><button class="danger" data-pl-delete="${i}">${t('remove')}</button></div></section>`).join('')||`<div class="card empty"><strong>${t('noTasks')}</strong></div>`}</div>`;bind('new-playlist',()=>playlistEditor());document.querySelectorAll('[data-pl-edit]').forEach(b=>b.onclick=()=>playlistEditor(playlists[b.dataset.plEdit]));document.querySelectorAll('[data-pl-delete]').forEach(b=>b.onclick=()=>confirmDialog(t('removeConfirm'),async()=>{await api('/api/v1/playlists/'+playlists[b.dataset.plDelete].id,{method:'DELETE'});await navigate();}));},
- async history(epoch){const ops=await api('/api/v1/operations');if(epoch!==state.epoch)return;$('#main').innerHTML=`<div class="section-heading"><h2>${t('history')}</h2>${buttons('history-refresh','refresh')}</div>${ops.some(x=>x.status==='UNKNOWN')?`<div class="notice warning">${t('unknown')}</div>`:''}<div class="card table-wrap">${ops.length?`<table><thead><tr>${['created','action','status','result','client','requestId'].map(x=>`<th>${t(x)}</th>`).join('')}</tr></thead><tbody>${ops.map((o,i)=>`<tr><td>${fmt(o.created_at)}</td><td>${esc(o.action)}<br><small>${esc(o.device_id)}</small></td><td><span class="badge ${['FAILED','UNKNOWN'].includes(o.status)?'bad':''}">${t(o.status)}</span>${o.status==='UNKNOWN'?`<div><button data-reconcile="${i}">${t('reconcile')}</button></div>`:''}</td><td>${esc(o.result?.image_id||o.result?.asset_id||o.error?.code||'—')}</td><td>${esc(o.client_id)}</td><td><code>${esc(o.request_id)}<br>${esc(o.operation_id)}</code></td></tr>`).join('')}</tbody></table>`:`<div class="empty">${t('noHistory')}</div>`}</div>`;bind('history-refresh',()=>navigate());document.querySelectorAll('[data-reconcile]').forEach(b=>b.onclick=busy(async()=>{const o=ops[b.dataset.reconcile];const r=await api('/api/v1/operations/'+o.operation_id+'/reconcile',{method:'POST',body:{acknowledge:false}});showModal(`<h2>${t('reconcile')}</h2><p>${t('current')}: ${esc(r.current_image_id)}</p><p>${t('result')}: ${esc(r.expected_image_id)}</p><p class="hint">${t('unknown')}</p><div class="modal-actions">${buttons('modal-cancel','cancel')}${r.resolved?'':buttons('acknowledge','acknowledge')}</div>`);bind('acknowledge',async()=>{await api('/api/v1/operations/'+o.operation_id+'/reconcile',{method:'POST',body:{acknowledge:true}});$('#modal').close();await navigate();});}));},
- async settings(){state.settings=await api('/api/v1/settings');const s=state.settings;$('#main').innerHTML=notice()+`<div class="columns"><section class="card"><h3>${t('settings')}</h3><div class="field"><label for="theme-select">${t('theme')}</label><select id="theme-select">${['system','light','dark'].map(x=>`<option value="${x}" ${state.theme===x?'selected':''}>${t(x==='system'?'systemTheme':x)}</option>`).join('')}</select></div><div class="field"><label for="language-select">${t('language')}</label><select id="language-select"><option value="zh" ${state.lang==='zh'?'selected':''}>简体中文</option><option value="en" ${state.lang==='en'?'selected':''}>English</option></select></div><p class="hint">${t('tokenHint')}</p>${buttons('logout','logout')}</section><section class="card"><h3>${t('auth')}</h3><div class="detail-grid">${detail('version',s.version)}${detail('writeProtection',t(!s.write_enabled?'yes':'no'))}${detail('keyConfigured',t(s.api_key_configured?'yes':'no'))}${detail('timezone',s.timezone)}</div><p class="hint">${t('refreshInterval')}</p><a href="/docs" target="_blank" rel="noopener">${t('apiDocs')} →</a><p class="hint">GET /openapi.json · /api/v1</p></section></div>`;$('#theme-select').onchange=()=>{state.theme=$('#theme-select').value;localStorage.setItem('ff-theme',state.theme);applyTheme();};$('#language-select').onchange=()=>{state.lang=$('#language-select').value;localStorage.setItem('ff-language',state.lang);navigate();};bind('logout',async()=>{await api('/api/v1/auth/logout',{method:'POST'});forgetLogin();shell();login();});accountSettings();}
+ async history(epoch){const ops=await api('/api/v1/operations');if(epoch!==state.epoch)return;$('#main').innerHTML=`<div class="section-heading"><h2>${t('history')}</h2>${buttons('history-refresh','refresh')}</div>${ops.some(x=>x.status==='UNKNOWN')?`<div class="notice warning">${t('unknown')}</div>`:''}<div class="card table-wrap">${ops.length?`<table><thead><tr>${['created','action','status','result','client','requestId'].map(x=>`<th>${t(x)}</th>`).join('')}</tr></thead><tbody>${ops.map((o,i)=>`<tr><td>${fmt(o.created_at)}</td><td>${esc(operationActionLabel(o.action))}<br><small>${esc(deviceNameForId(o.device_id))}</small></td><td><span class="history-status ${['FAILED','UNKNOWN'].includes(o.status)?'bad':''}">${t(o.status)}</span>${o.status==='UNKNOWN'?`<div><button data-reconcile="${i}">${t('reconcile')}</button></div>`:''}</td><td>${esc(o.result?.image_id||o.result?.asset_id||operationErrorLabel(o.error)||'—')}</td><td>${esc(operationClientLabel(o.client_id))}</td><td><code>${esc(o.request_id)}<br>${esc(o.operation_id)}</code></td></tr>`).join('')}</tbody></table>`:`<div class="empty">${t('noHistory')}</div>`}</div>`;bind('history-refresh',()=>navigate());document.querySelectorAll('[data-reconcile]').forEach(b=>b.onclick=busy(async()=>{const o=ops[b.dataset.reconcile];const r=await api('/api/v1/operations/'+o.operation_id+'/reconcile',{method:'POST',body:{acknowledge:false}});showModal(`<h2>${t('reconcile')}</h2><p>${t('current')}: ${esc(r.current_image_id)}</p><p>${t('result')}: ${esc(r.expected_image_id)}</p><p class="hint">${t('unknown')}</p><div class="modal-actions">${buttons('modal-cancel','cancel')}${r.resolved?'':buttons('acknowledge','acknowledge')}</div>`);bind('acknowledge',async()=>{await api('/api/v1/operations/'+o.operation_id+'/reconcile',{method:'POST',body:{acknowledge:true}});$('#modal').close();await navigate();});}));},
+ async settings(){state.settings=await api('/api/v1/settings');const s=state.settings;$('#main').innerHTML=notice()+`<div class="columns settings-columns"><section class="card"><h3>${t('settings')}</h3><div class="form-grid settings-preferences"><div class="field"><label for="theme-select">${t('theme')}</label><select id="theme-select">${['system','light','dark'].map(x=>`<option value="${x}" ${state.theme===x?'selected':''}>${t(x==='system'?'systemTheme':x)}</option>`).join('')}</select></div><div class="field"><label for="language-select">${t('language')}</label><select id="language-select"><option value="zh" ${state.lang==='zh'?'selected':''}>简体中文</option><option value="en" ${state.lang==='en'?'selected':''}>English</option></select></div></div><p class="hint">${t('tokenHint')}</p>${buttons('logout','logout')}</section><section class="card"><h3>${t('auth')}</h3><div class="detail-grid">${detail('version',s.version)}${detail('writeProtection',t(!s.write_enabled?'yes':'no'))}${detail('keyConfigured',t(s.api_key_configured?'yes':'no'))}${detail('timezone',s.timezone)}</div><p class="hint">${t('refreshInterval')}</p><a href="/docs" target="_blank" rel="noopener">${t('apiDocs')} →</a><p class="hint">GET /openapi.json · /api/v1</p></section></div>`;$('#theme-select').onchange=()=>{state.theme=$('#theme-select').value;localStorage.setItem('ff-theme',state.theme);applyTheme();};$('#language-select').onchange=()=>{state.lang=$('#language-select').value;localStorage.setItem('ff-language',state.lang);navigate();};bind('logout',async()=>{await api('/api/v1/auth/logout',{method:'POST'});forgetLogin();shell();login();});accountSettings();}
 };
 function jobPayload(j,changes={}){return {name:j.name,enabled:j.enabled,device_id:j.device_id,schedule:j.schedule,source:j.source,display_duration:j.display_duration,restore_previous:j.restore_previous,priority:j.priority,cleanup_unstarred:j.cleanup_unstarred||false,...changes};}
-async function jobEditor(job){const j=job||{name:'',enabled:true,device_id:state.device,schedule:{type:'daily',time:'07:00'},source:{type:'template',template:'daily-dashboard',data:{}},display_duration:5400,restore_previous:true,priority:50};showModal(`<h2>${t(job?'edit':'newJob')}</h2><form id="job-form"><div class="field"><label for="job-name">${t('name')}</label><input id="job-name" required maxlength="120" value="${esc(j.name)}"></div><div class="form-grid"><div class="field"><label for="job-schedule">${t('schedule')}</label><select id="job-schedule">${['daily','weekdays','weekends','cron','date','temporary'].map(x=>`<option ${j.schedule.type===x?'selected':''} value="${x}">${t(x)}</option>`).join('')}</select></div><div class="field"><label id="schedule-label" for="schedule-value">${t('time')}</label><input id="schedule-value" required value="${esc(j.schedule.time||j.schedule.cron||(j.schedule.at?j.schedule.at.slice(0,16):'07:00'))}"></div></div><div class="field"><label for="job-source">${t('source')} (JSON)</label><textarea id="job-source">${esc(JSON.stringify(j.source,null,2))}</textarea></div><div class="form-grid"><div class="field"><label for="job-duration">${t('duration')}</label><input id="job-duration" type="number" min="0" max="604800" value="${j.display_duration}"></div><div class="field"><label for="job-priority">${t('priority')}</label><input id="job-priority" type="number" min="0" max="100" value="${j.priority}"></div></div><label class="check-row"><input type="checkbox" id="job-enabled" ${j.enabled?'checked':''}>${t('enabled')}</label><label class="check-row"><input type="checkbox" id="job-restore" ${j.restore_previous?'checked':''}>${t('restoreAfter')}</label><div class="modal-actions">${buttons('modal-cancel','cancel')}<button type="submit" class="primary">${t('save')}</button></div></form>`);const source=$('#job-source');const choose=document.createElement('div');choose.className='field';choose.innerHTML=`<label for="job-template">${t('template')}</label><select id="job-template"><option value="">${t('advanced')}</option>${state.templates.map(x=>`<option value="${esc(x.id)}" ${j.source.template===x.id?'selected':''}>${esc(x.name)}</option>`).join('')}</select>`;source.parentElement.before(choose);$('#job-template').onchange=()=>{const id=$('#job-template').value;if(id)source.value=JSON.stringify({type:'template',template:id,data:{}},null,2);};function update(){const type=$('#job-schedule').value;$('#schedule-label').textContent=t(type==='cron'?'cron':['date','temporary'].includes(type)?'at':'time');$('#schedule-value').type=type==='cron'?'text':['date','temporary'].includes(type)?'datetime-local':'time';}$('#job-schedule').onchange=()=>{update();$('#schedule-value').value='';};update();$('#job-form').onsubmit=busy(async e=>{e.preventDefault();const type=$('#job-schedule').value,value=$('#schedule-value').value;const schedule={type};if(type==='cron')schedule.cron=value;else if(['date','temporary'].includes(type))schedule.at=value+':00+08:00';else schedule.time=value;const payload=jobPayload(j,{name:$('#job-name').value,schedule,source:JSON.parse($('#job-source').value),display_duration:Number($('#job-duration').value),priority:Number($('#job-priority').value),restore_previous:$('#job-restore').checked,cleanup_unstarred:false,enabled:$('#job-enabled').checked});await api('/api/v1/jobs'+(job?'/'+job.id:''),{method:job?'PUT':'POST',body:payload});$('#modal').close();await navigate();});await jobSourceEditor(j);}
-async function playlistEditor(p){p=p||{name:'',image_ids:[],interval_minutes:60,mode:'queue',enabled:false};showModal(`<h2>${t('playlists')}</h2><form id="playlist-form"><div class="field"><label for="playlist-name">${t('name')}</label><input id="playlist-name" required maxlength="120" value="${esc(p.name)}"></div><div class="field"><label for="playlist-images">${t('imageIds')}</label><input id="playlist-images" required value="${esc(p.image_ids.join(','))}" placeholder="1,2,3"></div><div class="form-grid"><div class="field"><label for="playlist-interval">${t('interval')}</label><input id="playlist-interval" type="number" min="5" max="10080" value="${p.interval_minutes}"></div><div class="field"><label for="playlist-mode">${t('mode')}</label><select id="playlist-mode"><option value="queue" ${p.mode==='queue'?'selected':''}>${t('queue')}</option><option value="random" ${p.mode==='random'?'selected':''}>${t('random')}</option></select></div></div><label class="check-row"><input id="playlist-enabled" type="checkbox" ${p.enabled?'checked':''}>${t('enabled')}</label><div class="modal-actions">${buttons('modal-cancel','cancel')}<button type="submit" class="primary">${t('save')}</button></div></form>`);$('#playlist-form').onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/playlists'+(p.id?'/'+p.id:''),{method:p.id?'PUT':'POST',body:{name:$('#playlist-name').value,device_id:p.device_id||state.device,image_ids:$('#playlist-images').value.split(',').map(x=>Number(x.trim())),interval_minutes:Number($('#playlist-interval').value),mode:$('#playlist-mode').value,enabled:$('#playlist-enabled').checked}});$('#modal').close();await navigate();});await playlistImagePicker(p);}
+async function playlistEditor(p){p=p||{name:'',image_ids:[],interval_minutes:60,mode:'queue',enabled:false};showModal(`<h2>${t('playlists')}</h2><form id="playlist-form"><div class="field"><label for="playlist-name">${t('name')}</label><input id="playlist-name" required maxlength="120" value="${esc(p.name)}"></div><div class="field"><label for="playlist-images">${t('imageIds')}</label><input id="playlist-images" required value="${esc(p.image_ids.join(','))}" placeholder="1,2,3"></div><div class="form-grid"><div class="field"><label for="playlist-interval">${t('interval')}</label><input id="playlist-interval" type="number" min="5" max="10080" value="${p.interval_minutes}"></div><div class="field"><label for="playlist-mode">${t('playbackMode')}</label><select id="playlist-mode"><option value="queue" ${p.mode==='queue'?'selected':''}>${t('queue')}</option><option value="random" ${p.mode==='random'?'selected':''}>${t('random')}</option></select></div></div><label class="check-row"><input id="playlist-enabled" type="checkbox" ${p.enabled?'checked':''}>${t('enabled')}</label><div class="modal-actions">${buttons('modal-cancel','cancel')}<button type="submit" class="primary">${t('save')}</button></div></form>`);$('#playlist-form').onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/playlists'+(p.id?'/'+p.id:''),{method:p.id?'PUT':'POST',body:{name:$('#playlist-name').value,device_id:p.device_id||state.device,image_ids:$('#playlist-images').value.split(',').map(x=>Number(x.trim())),interval_minutes:Number($('#playlist-interval').value),mode:$('#playlist-mode').value,enabled:$('#playlist-enabled').checked}});$('#modal').close();await navigate();});await playlistImagePicker(p);}
 $('#lang').onclick=()=>{state.lang=state.lang==='zh'?'en':'zh';localStorage.setItem('ff-language',state.lang);navigate();};$('#theme').onclick=()=>{state.theme=document.documentElement.dataset.theme==='dark'?'light':'dark';localStorage.setItem('ff-theme',state.theme);applyTheme();};$('#device').onchange=()=>{state.device=$('#device').value;navigate();};window.addEventListener('hashchange',()=>{const page=location.hash.slice(1);if(page!==state.page)navigate(page);});matchMedia('(prefers-color-scheme:dark)').addEventListener('change',applyTheme);
-applyTheme();shell();localStorage.removeItem('ff-login');(async()=>{try{const account=await api('/api/v1/auth/me');state.token=account.username;state.csrf=account.csrf_token;await loadConnection();}catch{forgetLogin();}await navigate();})();api('/api/v1/version').then(v=>$('#footer').innerHTML=`<span>Pigway Frame Flow · ${t('footer')}</span><span>v${esc(v.version)} · ${esc(v.commit.slice(0,8))} · ${esc(v.build_time)}</span>`).catch(()=>{});
+applyTheme();shell();localStorage.removeItem('ff-login');(async()=>{try{const account=await api('/api/v1/auth/me');state.token=account.username;state.csrf=account.csrf_token;await loadConnection();}catch{forgetLogin();}await navigate();})();api('/api/v1/version').then(v=>$('#footer').innerHTML=`<span>PIGWay Frame Flow · ${t('footer')}</span><span>v${esc(v.version)} · ${esc(v.commit.slice(0,8))} · ${esc(v.build_time)}</span>`).catch(()=>{});
 setInterval(()=>{if(state.token&&state.page==='dashboard'&&!$('#modal').open)navigate();},60000);
 
 // Keep Cron available for exceptional schedules, but make ordinary schedules form-based.
@@ -141,25 +157,25 @@ async function jobEditor(job){
  const base={name:'',enabled:true,device_id:state.device,schedule:{type:'daily',time:'07:00'},source:{type:'template',template:'daily-dashboard',data:{}},display_duration:5400,restore_previous:true,priority:50};
  const original=job||base;
  const j={...base,...original,schedule:normaliseSchedule(original.schedule||base.schedule)};
- const scheduleValue=j.schedule.time||j.schedule.cron||(j.schedule.at?j.schedule.at.slice(0,16):'07:00');
- showModal(`<h2>${t(job?'edit':'newJob')}</h2><form id="job-form"><div class="field"><label for="job-name">${t('name')}</label><input id="job-name" required maxlength="120" value="${esc(j.name)}"></div><div class="form-grid"><div class="field"><label for="job-schedule">${t('schedule')}</label><select id="job-schedule">${['daily','weekdays','weekends','date','temporary','cron'].map(type=>`<option value="${type}" ${j.schedule.type===type?'selected':''}>${scheduleTypeLabel(type)}</option>`).join('')}</select></div><div class="field"><label id="schedule-label" for="schedule-value">${t('time')}</label><input id="schedule-value" required value="${esc(scheduleValue)}"></div></div><p class="hint" id="schedule-hint"></p><div class="field"><label for="job-source">${t('source')} (JSON)</label><textarea id="job-source">${esc(JSON.stringify(j.source,null,2))}</textarea></div><div class="form-grid"><div class="field"><label for="job-duration">${t('duration')}</label><input id="job-duration" type="number" min="0" max="604800" value="${j.display_duration}"></div><div class="field"><label for="job-priority">${t('priority')}</label><input id="job-priority" type="number" min="0" max="100" value="${j.priority}"></div></div><label class="check-row"><input type="checkbox" id="job-enabled" ${j.enabled?'checked':''}>${t('enabled')}</label><label class="check-row"><input type="checkbox" id="job-restore" ${j.restore_previous?'checked':''}>${t('restoreAfter')}</label><p class="hint">${t('cloudKeepLatest')}</p><div class="modal-actions">${buttons('modal-cancel','cancel')}<button type="submit" class="primary">${t('save')}</button></div></form>`);
+ const scheduleValue=j.schedule.every||j.schedule.time||j.schedule.cron||(j.schedule.at?j.schedule.at.slice(0,16):'07:00');
+ showModal(`<h2>${t(job?.id?'edit':'newJob')}</h2><form id="job-form"><div class="field"><label for="job-name">${t('name')}</label><input id="job-name" required maxlength="120" value="${esc(j.name)}"></div><div class="form-grid"><div class="field"><label for="job-schedule">${t('schedule')}</label><select id="job-schedule">${['minutes','hours','daily','weekdays','weekends','date','temporary','cron'].map(type=>`<option value="${type}" ${j.schedule.type===type?'selected':''}>${scheduleTypeLabel(type)}</option>`).join('')}</select></div><div class="field"><label id="schedule-label" for="schedule-value">${t('time')}</label><input id="schedule-value" required value="${esc(scheduleValue)}"></div></div><p class="hint" id="schedule-hint"></p><div class="field"><label for="job-source">${t('source')} (JSON)</label><textarea id="job-source">${esc(JSON.stringify(j.source,null,2))}</textarea></div><div class="form-grid"><div class="field"><label for="job-duration">${t('duration')}</label><input id="job-duration" type="number" min="0" max="604800" value="${j.display_duration}"></div><div class="field"><label for="job-priority">${t('priority')}</label><input id="job-priority" type="number" min="0" max="100" value="${j.priority}"></div></div><label class="check-row"><input type="checkbox" id="job-enabled" ${j.enabled?'checked':''}>${t('enabled')}</label><label class="check-row"><input type="checkbox" id="job-restore" ${j.restore_previous?'checked':''}>${t('restoreAfter')}</label><p class="hint">${t('temporaryOptionsHint')}</p><p class="hint">${t('cloudKeepLatest')}</p><div class="modal-actions">${buttons('modal-cancel','cancel')}<button type="submit" class="primary">${t('save')}</button></div></form>`);
  const source=$('#job-source');
  const choose=document.createElement('div');
  choose.className='field';
  choose.innerHTML=`<label for="job-template">${t('template')}</label><select id="job-template"><option value="">${t('advanced')}</option>${state.templates.map(template=>`<option value="${esc(template.id)}" ${j.source.template===template.id?'selected':''}>${esc(template.name)}</option>`).join('')}</select>`;
  source.parentElement.before(choose);
  $('#job-template').onchange=()=>{const id=$('#job-template').value;if(id)source.value=JSON.stringify({type:'template',template:id,data:{}},null,2);};
- function updateScheduleField(){const type=$('#job-schedule').value;$('#schedule-label').textContent=type==='cron'?scheduleTypeLabel(type):t(['date','temporary'].includes(type)?'at':'time');$('#schedule-value').type=type==='cron'?'text':['date','temporary'].includes(type)?'datetime-local':'time';$('#schedule-hint').textContent=scheduleHint(type);}
+ function updateScheduleField(){const type=$('#job-schedule').value;const interval=['hours','minutes'].includes(type);$('#schedule-value').min=interval?'1':'';$('#schedule-value').max=type==='hours'?'168':type==='minutes'?'10080':'';$('#schedule-value').step=interval?'1':'';$('#schedule-label').textContent=interval?tr('间隔数值','Interval'):type==='cron'?scheduleTypeLabel(type):t(['date','temporary'].includes(type)?'at':'time');$('#schedule-value').type=interval?'number':type==='cron'?'text':['date','temporary'].includes(type)?'datetime-local':'time';$('#schedule-hint').textContent=scheduleHint(type);}
  $('#job-schedule').onchange=()=>{updateScheduleField();$('#schedule-value').value='';};
  updateScheduleField();
- $('#job-form').onsubmit=busy(async event=>{event.preventDefault();const type=$('#job-schedule').value;const value=$('#schedule-value').value;const schedule={type};if(type==='cron')schedule.cron=value;else if(['date','temporary'].includes(type))schedule.at=value+':00+08:00';else schedule.time=value;const payload=jobPayload(j,{name:$('#job-name').value,schedule,source:JSON.parse(source.value),display_duration:Number($('#job-duration').value),priority:Number($('#job-priority').value),restore_previous:$('#job-restore').checked,cleanup_unstarred:false,enabled:$('#job-enabled').checked});await api('/api/v1/jobs'+(job?'/'+job.id:''),{method:job?'PUT':'POST',body:payload});$('#modal').close();await navigate();});
+ $('#job-form').onsubmit=busy(async event=>{event.preventDefault();const type=$('#job-schedule').value;const value=$('#schedule-value').value;const schedule=['hours','minutes'].includes(type)?{type:'interval',interval_minutes:Number(value)*(type==='hours'?60:1)}:{type};if(['hours','minutes'].includes(type)){}else if(type==='cron')schedule.cron=value;else if(['date','temporary'].includes(type))schedule.at=value+':00+08:00';else schedule.time=value;const payload=jobPayload(j,{name:$('#job-name').value,schedule,source:JSON.parse(source.value),display_duration:Number($('#job-duration').value),priority:Number($('#job-priority').value),restore_previous:$('#job-restore').checked,cleanup_unstarred:false,enabled:$('#job-enabled').checked});await api('/api/v1/jobs'+(job?.id?'/'+job.id:''),{method:job?.id?'PUT':'POST',body:payload});$('#modal').close();await navigate();});
  await jobSourceEditor(j);
 }
 
 views.automation=async epoch=>{
  const jobs=await api('/api/v1/jobs');
  if(epoch!==state.epoch)return;
- $('#main').innerHTML=notice()+`<div class="section-heading"><p class="hint">Asia/Shanghai · ${t('automation')}</p>${buttons('new-job','newJob',true)}</div><div class="card">${jobs.length?`<div class="table-wrap"><table><thead><tr>${['name','schedule','status','nextRun','lastRun','result','action'].map(key=>`<th>${t(key)}</th>`).join('')}</tr></thead><tbody>${jobs.map((job,index)=>`<tr><td><strong>${esc(job.name)}</strong><br><small>${esc(job.device_id)}</small></td><td>${esc(scheduleSummary(job.schedule))}</td><td><span class="badge">${t(job.enabled?'enabled':'disabled')}</span></td><td>${fmt(job.next_run)}</td><td>${fmt(job.last_run)}</td><td><code>${esc(job.last_result)}</code></td><td><div class="row-actions"><button data-job-edit="${index}">${t('edit')}</button><button data-job-toggle="${index}">${t(job.enabled?'disabled':'enabled')}</button><button class="danger" data-job-delete="${index}">${t('remove')}</button></div></td></tr>`).join('')}</tbody></table></div>`:`<div class="empty"><strong>${t('noTasks')}</strong></div>`}</div>`;
+ $('#main').innerHTML=notice()+`<div class="section-heading"><p class="hint">${state.lang==='zh'?'上海时间':'Shanghai time'} · ${t('automation')}</p>${buttons('new-job','newJob',true)}</div><div class="card">${jobs.length?`<div class="table-wrap"><table class="automation-table"><thead><tr>${['name','targetFrame','schedule','status','nextRun','lastRun','result','action'].map(key=>`<th>${key==='targetFrame'?tr('目标相框','Target frame'):t(key)}</th>`).join('')}</tr></thead><tbody>${jobs.map((job,index)=>`<tr><td><strong>${esc(job.name)}</strong></td><td>${esc(deviceDisplayName(state.devices.find(d=>d.id===job.device_id)||{id:job.device_id,name:job.device_id}))}</td><td>${esc(scheduleSummary(job.schedule))}</td><td><span class="automation-status">${t(job.enabled?'enabled':'disabled')}</span></td><td>${fmt(job.next_run)}</td><td>${fmt(job.last_run)}</td><td><code>${esc(job.last_result)}</code></td><td><div class="row-actions"><button data-job-edit="${index}">${t('edit')}</button><button data-job-toggle="${index}">${t(job.enabled?'disabled':'enabled')}</button><button class="danger" data-job-delete="${index}">${t('remove')}</button></div></td></tr>`).join('')}</tbody></table></div>`:`<div class="empty"><strong>${t('noTasks')}</strong></div>`}</div>`;
  bind('new-job',()=>jobEditor());
  document.querySelectorAll('[data-job-edit]').forEach(button=>button.onclick=()=>jobEditor(jobs[button.dataset.jobEdit]));
  document.querySelectorAll('[data-job-toggle]').forEach(button=>button.onclick=busy(async()=>{const job=jobs[button.dataset.jobToggle];await api('/api/v1/jobs/'+job.id,{method:'PUT',body:jobPayload(job,{enabled:!job.enabled})});await navigate();}));

pigway_frame_flow/web/extensions.js

@@ -29,7 +29,7 @@ async function connectionsPage(){
  await aiSettingsPanel();await aiImagePanel();await storageSettingsPanel();await clientsPanel();await webhooksPanel();await externalProvidersPanel();await mqttPanel();
 }
 async function aiSettingsPanel(){
- const config=await api('/api/v1/settings/ai-layout');const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>${tr('AI 排版 · OpenAI 兼容','AI layout · OpenAI compatible')}</h3><p class="hint">${tr('只发送文字、尺寸和排版要求，不发送照片。填写完整 chat/completions 地址；使用服务商的模型名称。','Only text, dimensions and instructions are sent; never photos. Enter the full chat/completions URL and provider model name.')}</p><form id="ai-settings-form"><div class="field"><label for="ai-endpoint">Endpoint</label><input id="ai-endpoint" type="url" value="${esc(config.endpoint)}" placeholder="https://…/v1/chat/completions"></div><div class="field"><label for="ai-model">Model</label><input id="ai-model" value="${esc(config.model)}"></div><div class="field"><label for="ai-key">${tr('API Key（留空保留已有密钥）','API key (blank keeps existing)')}</label><input id="ai-key" type="password" autocomplete="off"><p class="hint">${t('keyConfigured')}: ${t(config.key_configured?'yes':'no')}</p></div><button type="submit">${t('save')}</button></form>`;$('#main').append(card);$('#ai-settings-form').onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/settings/ai-layout',{method:'PUT',body:{endpoint:$('#ai-endpoint').value,model:$('#ai-model').value}});const key=$('#ai-key').value;$('#ai-key').value='';if(key)await api('/api/v1/settings/ai-layout/key',{method:'PUT',body:{key}});toast(t('done'));});
+ const config=await api('/api/v1/settings/ai-layout');const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>${tr('AI 排版 · OpenAI 兼容','AI layout · OpenAI compatible')}</h3><p class="hint">${tr('只发送文字、尺寸和排版要求，不发送照片。填写完整 chat/completions 地址；使用服务商的模型名称。','Only text, dimensions and instructions are sent; never photos. Enter the full chat/completions URL and provider model name.')}</p><form id="ai-settings-form"><div class="field"><label for="ai-endpoint">Endpoint</label><input id="ai-endpoint" type="url" value="${esc(config.endpoint)}" placeholder="https://…/v1/chat/completions"></div><div class="field"><label for="ai-model">Model</label><input id="ai-model" value="${esc(config.model)}"></div><div class="field"><label for="ai-key">${tr('API Key（留空保留已有密钥）','API key (blank keeps existing)')}</label><input id="ai-key" type="password" autocomplete="off"><p class="hint">${t('apiKeyConfigured')}: ${t(config.key_configured?'yes':'no')}</p></div><button type="submit">${t('save')}</button></form>`;$('#main').append(card);$('#ai-settings-form').onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/settings/ai-layout',{method:'PUT',body:{endpoint:$('#ai-endpoint').value,model:$('#ai-model').value}});const key=$('#ai-key').value;$('#ai-key').value='';if(key)await api('/api/v1/settings/ai-layout/key',{method:'PUT',body:{key}});toast(t('done'));});
 }
 async function storageSettingsPanel(){
  const data=await api('/api/v1/storage');const p=data.policy;const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>${tr('本地图库保留策略','Local storage retention')}</h3><p>${data.asset_count} ${t('count')} · ${(data.total_bytes/1024/1024).toFixed(1)} MiB · ${tr('受保护','Protected')}: ${data.protected_count}</p><p class="hint">${tr('仅清理生成图和预览缓存；手动上传、星标、当前/恢复图片以及任务/模板引用会保留。不会删除 NAS 原照片或云端图片。先查看清理预估，再开启自动清理。','Only generated images and preview cache are cleaned. Manual uploads, stars, current/restore content and task/template references are retained. NAS originals and cloud images are untouched. Preview cleanup before enabling it.')}</p><form id="storage-policy"><label class="check-row"><input id="storage-enabled" type="checkbox" ${p.enabled?'checked':''}>${t('enabled')}</label><div class="form-grid"><div class="field"><label for="storage-days">${tr('生成图保留天数','Generated image retention days')}</label><input id="storage-days" type="number" min="1" value="${p.generated_days}"></div><div class="field"><label for="storage-cache-days">${tr('缓存保留天数','Cache retention days')}</label><input id="storage-cache-days" type="number" min="1" value="${p.cache_days}"></div><div class="field"><label for="storage-size">${tr('容量目标 MiB','Target size MiB')}</label><input id="storage-size" type="number" min="1" value="${p.max_bytes/1024/1024}"></div></div><div class="actions"><button type="submit">${t('save')}</button><button id="storage-preview" type="button">${tr('预估清理','Preview cleanup')}</button></div><p id="storage-estimate"></p></form>`;$('#main').append(card);$('#storage-policy').onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/storage/policy',{method:'PUT',body:{enabled:$('#storage-enabled').checked,generated_days:Number($('#storage-days').value),cache_days:Number($('#storage-cache-days').value),max_bytes:Number($('#storage-size').value)*1024*1024}});toast(t('done'));});bind('storage-preview',async()=>{const result=await api('/api/v1/storage/cleanup?dry_run=true',{method:'POST'});$('#storage-estimate').textContent=result.disabled?tr('策略未启用；不会清理','Policy disabled; nothing is removed'):tr('可清理 ','Eligible: ')+result.deleted+' · '+(result.bytes_freed/1024/1024).toFixed(1)+' MiB';});
@@ -49,11 +49,11 @@ async function officialWidgetControls(info,data){
  const send=cover_id=>confirmDialog(tr('此操作会改变官方订阅和画框内容，是否继续？','This changes the official subscription and frame content. Continue?'),async()=>{const args=cover_id?Object.fromEntries([...document.querySelectorAll('[data-widget-arg]')].filter(x=>x.value).map(x=>[x.dataset.widgetArg,x.value])):{};const r=await api('/api/v1/devices/'+state.device+'/widgets/selection',{method:'POST',body:{cover_id,args},headers:{'Idempotency-Key':'widget-'+clientUUID()}});await waitOperation(r.operation_id);await navigate('templates');});if(!disabled){$('#official-widget-use').onclick=busy(()=>send(Number($('#official-widget-choice').value)));$('#official-widget-cancel').onclick=busy(()=>send(null));}
 }
 function addPhotoQualityFields(source){
- const box=document.createElement('section');box.innerHTML=`<div id="source-local-quality"><h3>${tr('照片筛选','Photo filtering')}</h3><p class="hint">${tr('按小图清晰度、亮度和相似度筛选，不改动或删除 NAS 原照片；无法保证识别闭眼。建议先用低阈值。个人空间还需要将相应目录只读挂载到 /photos。','Filters thumbnail sharpness, brightness and similarity without modifying or deleting originals. Closed-eye detection is not guaranteed. Start with low thresholds. Personal space also requires mounting its folder read-only at /photos.')}</p><div class="field"><label for="source-people-space">${tr('人物空间','People space')}</label><select id="source-people-space"><option value="shared">${tr('共享空间','Shared space')}</option><option value="personal">${tr('个人空间','Personal space')}</option></select></div><div class="form-grid"><div class="field"><label for="source-sharpness">${tr('最低清晰度（0 不筛选）','Minimum sharpness (0 disables)')}</label><input id="source-sharpness" type="number" min="0" max="10000" value="${source?.minimum_sharpness||0}"></div><div class="field"><label for="source-bright-min">${tr('最低亮度','Minimum brightness')}</label><input id="source-bright-min" type="number" min="0" max="255" value="${source?.minimum_brightness||0}"></div><div class="field"><label for="source-bright-max">${tr('最高亮度','Maximum brightness')}</label><input id="source-bright-max" type="number" min="0" max="255" value="${source?.maximum_brightness??255}"></div></div><label class="check-row"><input id="source-dedup" type="checkbox" ${source?.avoid_duplicates?'checked':''}>${tr('避开最近 200 张的相似照片','Avoid photos similar to the last 200 selections')}</label></div><div class="field"><label for="source-oauth">${tr('网盘 OAuth 凭据 JSON（可选；仅原生网盘）','Drive OAuth credentials JSON (optional; native drives only)')}</label><input id="source-oauth" type="password" autocomplete="off" placeholder='{"access_token":"…","drive_id":"…"}'></div>`;$('#photo-source-form .modal-actions').before(box);$('#source-people-space').value=source?.people_space||'shared';
+ const box=document.createElement('section');box.innerHTML=`<div id="source-local-quality"><h3>${tr('照片筛选','Photo filtering')}</h3><p class="hint">${tr('对 API 获取的预览图按清晰度、亮度和相似度筛选，不修改或删除 NAS 原照片；无法保证识别闭眼。建议先使用较低阈值。','Filters API previews by sharpness, brightness and similarity without modifying or deleting NAS originals. Closed-eye detection is not guaranteed. Start with low thresholds.')}</p><div class="field"><label for="source-people-space">${tr('照片空间','Photo space')}</label><select id="source-people-space"><option value="shared">${tr('共享空间','Shared space')}</option><option value="personal">${tr('个人空间','Personal space')}</option></select></div><div class="form-grid">${[['short','minimum_short_edge',tr('最小短边（像素）','Minimum short edge (px)')],['long','minimum_long_edge',tr('最小长边（像素）','Minimum long edge (px)')]].map(([id,key,label])=>`<div class="field"><label for="source-min-${id}">${label}</label><input id="source-min-${id}" type="number" min="0" max="50000" step="1" value="${source?.[key]||0}"></div>`).join('')}</div><p class="hint">${tr('0 表示不限制；按源照片和实际取得的预览图像素筛选，横竖图通用。可从短边 1200、长边 1600 开始设置；分辨率不代表对焦清晰度。','0 disables. Checks source and downloaded preview dimensions regardless of orientation. Start with short edge 1200 and long edge 1600; pixel count does not measure focus.')}</p><div class="form-grid"><div class="field"><label for="source-sharpness">${tr('最低清晰度（0 不筛选）','Minimum sharpness (0 disables)')}</label><input id="source-sharpness" type="number" min="0" max="10000" value="${source?.minimum_sharpness||0}"></div><div class="field"><label for="source-bright-min">${tr('最低亮度','Minimum brightness')}</label><input id="source-bright-min" type="number" min="0" max="255" value="${source?.minimum_brightness||0}"></div><div class="field"><label for="source-bright-max">${tr('最高亮度','Maximum brightness')}</label><input id="source-bright-max" type="number" min="0" max="255" value="${source?.maximum_brightness??255}"></div></div><label class="check-row"><input id="source-dedup" type="checkbox" ${source?.avoid_duplicates?'checked':''}>${tr('避开最近 200 张的相似照片','Avoid photos similar to the last 200 selections')}</label></div><div class="field"><label for="source-oauth">${tr('网盘 OAuth 凭据 JSON（可选；仅原生网盘）','Drive OAuth credentials JSON (optional; native drives only)')}</label><input id="source-oauth" type="password" autocomplete="off" placeholder='{"access_token":"…","drive_id":"…"}'></div>`;$('#photo-source-form .modal-actions').before(box);$('#source-people-space').value=source?.people_space||'shared';
 
 }
 async function aiImagePanel(){
- const info=await api('/api/v1/settings/ai-images');const conf=info.config||{};const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>${tr('AI 生图','AI image generation')}</h3><p class="hint">${tr('独立配置 images/generations 接口。每次仅生成一张并保存本地，不会自动显示到画框。请求可能收费，失败不自动重试。','Configure a separate images/generations endpoint. One image is saved locally per request, never automatically displayed. Requests may be billed; failures are not retried.')}</p><form id="image-ai-config"><div class="field"><label for="image-ai-url">Endpoint</label><input id="image-ai-url" type="url" required value="${esc(conf.endpoint||'')}"></div><div class="field"><label for="image-ai-model">Model</label><input id="image-ai-model" required value="${esc(conf.model||'')}"></div><div class="field"><label for="image-ai-size">Size</label><select id="image-ai-size"><option>1024x1536</option><option>1536x1024</option><option>1024x1024</option></select></div><div class="field"><label for="image-ai-key">API Key</label><input id="image-ai-key" type="password" autocomplete="off"><p class="hint">${t('keyConfigured')}: ${t(info.key_configured?'yes':'no')}</p></div><button type="submit">${t('save')}</button></form><form id="image-ai-generate"><div class="field"><label for="image-ai-prompt">${tr('画面描述','Image prompt')}</label><textarea id="image-ai-prompt" required maxlength="4000"></textarea></div><button type="submit">${tr('生成一张（可能收费）','Generate one image (may incur charges)')}</button></form><div id="image-ai-preview"></div>`;$('#main').append(card);$('#image-ai-size').value=conf.size||'1024x1536';$('#image-ai-config').onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/settings/ai-images',{method:'PUT',body:{endpoint:$('#image-ai-url').value,model:$('#image-ai-model').value,size:$('#image-ai-size').value}});const key=$('#image-ai-key').value;$('#image-ai-key').value='';if(key)await api('/api/v1/settings/ai-images/key',{method:'PUT',body:{key}});toast(t('done'));});$('#image-ai-generate').onsubmit=busy(async e=>{e.preventDefault();const result=await api('/api/v1/ai/images',{method:'POST',body:{prompt:$('#image-ai-prompt').value},headers:{'Idempotency-Key':'ai-image-'+clientUUID()}});const op=await waitOperation(result.operation_id);$('#image-ai-preview').innerHTML='<img class="preview" id="image-ai-result" alt="Generated image">';await blobImage($('#image-ai-result'),op.result.url);toast(tr('已存入本地图库','Saved to local gallery'));});
+ const info=await api('/api/v1/settings/ai-images');const conf=info.config||{};const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>${tr('AI 生图','AI image generation')}</h3><p class="hint">${tr('独立配置 images/generations 接口。每次仅生成一张并保存本地，不会自动显示到画框。请求可能收费，失败不自动重试。','Configure a separate images/generations endpoint. One image is saved locally per request, never automatically displayed. Requests may be billed; failures are not retried.')}</p><form id="image-ai-config"><div class="field"><label for="image-ai-url">Endpoint</label><input id="image-ai-url" type="url" required value="${esc(conf.endpoint||'')}"></div><div class="field"><label for="image-ai-model">Model</label><input id="image-ai-model" required value="${esc(conf.model||'')}"></div><div class="field"><label for="image-ai-size">Size</label><select id="image-ai-size"><option>1024x1536</option><option>1536x1024</option><option>1024x1024</option></select></div><div class="field"><label for="image-ai-key">API Key</label><input id="image-ai-key" type="password" autocomplete="off"><p class="hint">${t('apiKeyConfigured')}: ${t(info.key_configured?'yes':'no')}</p></div><button type="submit">${t('save')}</button></form><form id="image-ai-generate"><div class="field"><label for="image-ai-prompt">${tr('画面描述','Image prompt')}</label><textarea id="image-ai-prompt" required maxlength="4000"></textarea></div><button type="submit">${tr('生成一张（可能收费）','Generate one image (may incur charges)')}</button></form><div id="image-ai-preview"></div>`;$('#main').append(card);$('#image-ai-size').value=conf.size||'1024x1536';$('#image-ai-config').onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/settings/ai-images',{method:'PUT',body:{endpoint:$('#image-ai-url').value,model:$('#image-ai-model').value,size:$('#image-ai-size').value}});const key=$('#image-ai-key').value;$('#image-ai-key').value='';if(key)await api('/api/v1/settings/ai-images/key',{method:'PUT',body:{key}});toast(t('done'));});$('#image-ai-generate').onsubmit=busy(async e=>{e.preventDefault();const result=await api('/api/v1/ai/images',{method:'POST',body:{prompt:$('#image-ai-prompt').value},headers:{'Idempotency-Key':'ai-image-'+clientUUID()}});const op=await waitOperation(result.operation_id);$('#image-ai-preview').innerHTML='<img class="preview" id="image-ai-result" alt="Generated image">';await blobImage($('#image-ai-result'),op.result.url);toast(tr('已存入本地图库','Saved to local gallery'));});
 }
 async function mqttPanel(){
  const status=await api('/api/v1/integrations/mqtt');const c=status.config;const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>MQTT · ${t(status.connected?'connected':'disconnected')}</h3><p class="hint">${tr('默认关闭。须配置环境 Secret FRAME_FLOW_MQTT_TOKEN（有 display:write 权限的客户端 Token），以及可选 FRAME_FLOW_MQTT_PASSWORD。消息必须携带 request_id；retained 消息被拒绝。结果发送到命令主题的 /result。','Disabled by default. Configure FRAME_FLOW_MQTT_TOKEN with display:write scope and optional FRAME_FLOW_MQTT_PASSWORD as environment secrets. Commands require request_id; retained commands are rejected. Results are published to the command topic plus /result.')}</p><form id="mqtt-config"><label class="check-row"><input id="mqtt-enabled" type="checkbox" ${c.enabled?'checked':''}>${t('enabled')}</label><div class="field"><label for="mqtt-host">Host</label><input id="mqtt-host" value="${esc(c.host)}"></div><div class="field"><label for="mqtt-port">Port</label><input id="mqtt-port" type="number" min="1" max="65535" value="${c.port}"></div><div class="field"><label for="mqtt-topic">Topic</label><input id="mqtt-topic" value="${esc(c.topic)}"></div><div class="field"><label for="mqtt-username">${t('username')}</label><input id="mqtt-username" value="${esc(c.username)}"></div><label class="check-row"><input id="mqtt-tls" type="checkbox" ${c.tls?'checked':''}>TLS</label><label class="check-row"><input id="mqtt-lan" type="checkbox" ${c.allow_insecure_lan?'checked':''}>${tr('明确允许 LAN 明文连接','Explicitly allow plaintext LAN connection')}</label><button type="submit">${t('save')}</button></form>`;$('#main').append(card);$('#mqtt-config').onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/integrations/mqtt',{method:'PUT',body:{enabled:$('#mqtt-enabled').checked,host:$('#mqtt-host').value,port:Number($('#mqtt-port').value),topic:$('#mqtt-topic').value,username:$('#mqtt-username').value,tls:$('#mqtt-tls').checked,allow_insecure_lan:$('#mqtt-lan').checked}});toast(t('done'));});

pigway_frame_flow/web/features.js

@@ -14,7 +14,7 @@ function editTemplateSource(source){state.selectedTemplate=source.template;state
 async function enhanceDashboard(){
  const epoch=state.epoch;const frame=$('.frame-demo');const panel=document.createElement('section');panel.className='card';$('#main').append(panel);
  const current=await currentPanel(panel);if(epoch!==state.epoch)return;
- if(current.preview_url){frame.innerHTML=`<img id="current-frame-image" alt="${t('currentContent')}" style="width:100%;height:100%;object-fit:contain"><span class="frame-label">${t('currentContent')} #${current.image_id}</span>`;void blobImage($('#current-frame-image'),current.preview_url);}else{frame.innerHTML=`<div class="mini-art"><div class="sun"></div></div><span class="frame-label">${t('testLabel')}</span>`;}
+ if(current.preview_url){frame.innerHTML=`<button id="current-frame-preview" class="current-frame-preview" aria-label="${t('original')} · ${t('currentContent')} #${esc(current.image_id)}"><img id="current-frame-image" alt="${t('currentContent')}"></button><span class="frame-label">${t('currentContent')} #${esc(current.image_id)}</span>`;const original=new URL(current.preview_url,location.origin);original.searchParams.delete('thumbnail');bind('current-frame-preview',()=>openImageViewer(original.pathname+original.search,`${t('currentContent')} #${current.image_id}`));void blobImage($('#current-frame-image'),original.pathname+original.search);}else{frame.innerHTML=`<div class="mini-art"><div class="sun"></div></div><span class="frame-label">${t('testLabel')}</span>`;}
  const weather=await api('/api/v1/providers/weather');if(epoch!==state.epoch)return;const box=document.createElement('section');box.className='card';box.innerHTML=`<h3>${t('weather')}</h3><p>${esc(weather.current.location)} · ${esc(weather.current.temperature)} · ${esc(weather.current.summary)}</p><p class="hint">${weather.current.mock?t('weatherMock'):t('weatherAttribution')}${weather.current.stale?' · '+t('stale'):''}</p>`;$('#main').append(box);
 }
 async function enhanceTemplates(){
@@ -28,23 +28,24 @@ async function enhanceTemplates(){
 async function downloadImage(path,name){const blob=await api(path,{binary:true});const url=URL.createObjectURL(blob);const link=document.createElement('a');link.href=url;link.download=name;document.body.append(link);link.click();link.remove();setTimeout(()=>URL.revokeObjectURL(url),10000);}
 function displayDialog(content){
  if(!liveWriteAllowed()){toast(t('readOnlyWarning'));return;}
- showModal(`<h2>${t('displayOptions')}</h2><form id="display-options"><label class="check-row"><input id="override-restore" type="checkbox">${t('restoreAfter')}</label><div class="form-grid"><div class="field"><label for="override-duration">${t('duration')}</label><input id="override-duration" type="number" min="1" max="604800" value="1800"></div><div class="field"><label for="override-priority">${t('priority')}</label><input id="override-priority" type="number" min="0" max="100" value="50"></div></div><div class="modal-actions">${buttons('modal-cancel','cancel')}<button id="confirm-display" type="submit" class="primary">${t('display')}</button></div></form>`);
+ showModal(`<h2>${t('displayOptions')}</h2><form id="display-options"><p class="hint">${t('temporaryOptionsHint')}</p><label class="check-row"><input id="override-restore" type="checkbox">${t('restoreAfter')}</label><div class="form-grid"><div class="field"><label for="override-duration">${t('duration')}</label><input id="override-duration" type="number" min="1" max="604800" value="1800"></div><div class="field"><label for="override-priority">${t('priority')}</label><input id="override-priority" type="number" min="0" max="100" value="50"></div></div><div class="modal-actions">${buttons('modal-cancel','cancel')}<button id="confirm-display" type="submit" class="primary">${t('display')}</button></div></form>`);
  $('#display-options').onsubmit=busy(async e=>{e.preventDefault();const restore=$('#override-restore').checked;const options={duration:restore?Number($('#override-duration').value):0,restore_previous:restore,priority:Number($('#override-priority').value)};await accepted('/api/v1/display',{device_id:state.device,content,options});$('#modal').close();await navigate('history');});
 }
 function enhanceGallery(){
  const grid=$('.gallery');if(!grid)return;
- const controls=document.createElement('div');controls.className='form-grid';controls.innerHTML=`<div class="field"><label for="gallery-search">${t('searchImages')}</label><input id="gallery-search" type="search"></div><div class="field"><label for="gallery-sort">${t('mode')}</label><select id="gallery-sort"><option value="newest">${t('sortNewest')}</option><option value="oldest">${t('sortOldest')}</option><option value="name">${t('sortName')}</option></select></div>`;grid.before(controls);
- if(state.tab==='local'){const bar=document.createElement('div');bar.className='actions';bar.innerHTML=`<select id="asset-origin" aria-label="${t('originFilter')}">${['all','manual','task','external','template','unknown'].map(x=>`<option value="${x}">${t('origin_'+x)}</option>`).join('')}</select><select id="asset-job" aria-label="${t('taskOrigin')}"><option value="">${t('allTasks')}</option></select><button id="asset-prev">${t('previousPage')}</button><button id="asset-next">${t('nextPage')}</button><button id="asset-all">${t('selectAll')}</button><button id="asset-batch-star">${t('star')}</button><button id="asset-batch-unstar">${t('unstar')}</button><button id="asset-batch-delete" class="danger">${t('deleteSelected')}</button>`;grid.before(bar);$('#asset-origin').value=state.assetOrigin||'all';void api('/api/v1/jobs').then(jobs=>{if(!bar.isConnected)return;const picker=bar.querySelector('#asset-job');for(const job of jobs){const option=document.createElement('option');option.value=job.id;option.textContent=job.name;picker.append(option);}picker.value=state.assetJob||'';}).catch(error=>{if(bar.isConnected)toast(error.message);});$('#asset-origin').onchange=()=>{state.assetOffset=0;state.assetOrigin=$('#asset-origin').value;return navigate();};$('#asset-job').onchange=()=>{state.assetOffset=0;state.assetJob=$('#asset-job').value;state.assetOrigin=state.assetJob?'task':state.assetOrigin;return navigate();};$('#asset-prev').disabled=!(state.assetOffset||0);$('#asset-next').disabled=state.gallery.length<200;bind('asset-prev',()=>{state.assetOffset=Math.max(0,(state.assetOffset||0)-200);return navigate();});bind('asset-next',()=>{state.assetOffset=(state.assetOffset||0)+200;return navigate();});$('#asset-all').onclick=()=>{const boxes=[...document.querySelectorAll('.asset-select')].filter(x=>!x.closest('.image-card').hidden);const checked=boxes.some(x=>!x.checked);boxes.forEach(x=>x.checked=checked);};for(const action of ['star','unstar','delete']){bind('asset-batch-'+action,async()=>{const ids=[...document.querySelectorAll('.asset-select:checked')].map(x=>x.dataset.asset);if(!ids.length){toast(t('selectImagesFirst'));return;}if(action==='delete'&&!confirm(t('deleteSelectedConfirm')))return;const results=[];for(let i=0;i<ids.length;i+=100){const r=await api('/api/v1/assets/batch',{method:'POST',body:{asset_ids:ids.slice(i,i+100),action}});results.push(...r.results);}const failed=results.filter(x=>x.status==='failed');if(failed.length)toast(t('batchFailed')+' '+failed.length);await navigate();});}}
- const cards=[...grid.querySelectorAll('.image-card')];$('#gallery-search').oninput=()=>{const query=$('#gallery-search').value.toLowerCase();cards.forEach(card=>card.hidden=!card.textContent.toLowerCase().includes(query));};$('#gallery-sort').onchange=()=>{const order=$('#gallery-sort').value;const indexes=cards.map((card,index)=>({card,item:state.gallery[index]}));indexes.sort((a,b)=>order==='name'?a.item.name.localeCompare(b.item.name):order==='oldest'?String(a.item.created_at).localeCompare(String(b.item.created_at)):String(b.item.created_at).localeCompare(String(a.item.created_at)));indexes.forEach(x=>grid.append(x.card));};
- cards.forEach((card,i)=>{const item=state.gallery[i];if(state.tab==='local'){const star=document.createElement('button');star.textContent=t(item.starred?'unstar':'star');star.setAttribute('aria-pressed',String(item.starred));card.querySelector('.actions').append(star);star.onclick=busy(async()=>{await api('/api/v1/assets/'+item.asset_id+'/star',{method:'PUT',body:{starred:!item.starred}});await navigate();});const label=document.createElement('small');label.textContent=item.origin==='task'?t('taskOrigin')+' · '+(item.job_name||item.job_id):t('origin_'+item.origin);card.querySelector('h3').after(label);const select=document.createElement('input');select.type='checkbox';select.className='asset-select';select.dataset.asset=item.asset_id;select.setAttribute('aria-label',t('selectImage'));card.prepend(select);}if(item.width&&item.height){const dimensions=document.createElement('small');dimensions.textContent=item.width+' × '+item.height;card.querySelector('h3').after(dimensions);}const download=document.createElement('button');download.textContent=t('download');card.querySelector('.actions').append(download);download.onclick=busy(()=>downloadImage(item.url,item.name));if(state.tab==='local'){const edit=document.createElement('button');edit.textContent=t('continueEdit');card.querySelector('.actions').append(edit);edit.onclick=busy(async()=>{const meta=await api('/api/v1/assets/'+item.asset_id+'/source');if(meta.source?.type==='template')await editTemplateSource(meta.source);else toast(t('sourceUnknown'));});}});
+ const controls=document.createElement('div');controls.className='form-grid gallery-filters';controls.innerHTML=`<div class="field"><label for="gallery-search">${t('searchImages')}</label><input id="gallery-search" type="search"></div><div class="field"><label for="gallery-sort">${t('sortOrder')}</label><select id="gallery-sort"><option value="newest">${t('sortNewest')}</option><option value="oldest">${t('sortOldest')}</option><option value="name">${t('sortName')}</option></select></div>`;grid.before(controls);
+ if(state.tab==='local'){controls.classList.add('gallery-filters-local');const bar=document.createElement('div');bar.className='actions';bar.innerHTML=`<select id="asset-origin" aria-label="${t('originFilter')}">${['all','manual','task','external','template','unknown'].map(x=>`<option value="${x}">${t('origin_'+x)}</option>`).join('')}</select><select id="asset-job" aria-label="${t('taskOrigin')}"><option value="">${t('allTasks')}</option></select><button id="asset-prev">${t('previousPage')}</button><button id="asset-next">${t('nextPage')}</button><button id="asset-all">${t('selectAll')}</button><button id="asset-invert">${t('invertSelection')}</button><button id="asset-batch-star">${t('star')}</button><button id="asset-batch-unstar">${t('unstar')}</button><button id="asset-batch-delete" class="danger">${t('deleteSelected')}</button>`;grid.before(bar);for(const [id,key] of [['asset-origin','originFilter'],['asset-job','taskOrigin']]){const field=document.createElement('div');field.className='field';const label=document.createElement('label');label.htmlFor=id;label.textContent=t(key);field.append(label,bar.querySelector('#'+id));controls.append(field);}const help=document.createElement('p');help.className='hint';help.id='gallery-selection-help';help.textContent=t('gallerySelectionHelp')+' '+t('starHelp');grid.before(help);bar.setAttribute('aria-describedby',help.id);$('#asset-origin').value=state.assetOrigin||'all';if(state.galleryJobsEpoch!==state.epoch){state.galleryJobsEpoch=state.epoch;state.galleryJobsRequest=api('/api/v1/jobs');}void state.galleryJobsRequest.then(jobs=>{if(!bar.isConnected)return;const picker=bar.querySelector('#asset-job');for(const job of jobs){const option=document.createElement('option');option.value=job.id;option.textContent=job.name;picker.append(option);}picker.value=state.assetJob||'';}).catch(error=>{if(bar.isConnected)toast(error.message);});$('#asset-origin').onchange=()=>{state.assetOffset=0;state.assetOrigin=$('#asset-origin').value;return navigate();};$('#asset-job').onchange=()=>{state.assetOffset=0;state.assetJob=$('#asset-job').value;state.assetOrigin=state.assetJob?'task':state.assetOrigin;return navigate();};$('#asset-prev').disabled=!(state.assetOffset||0);$('#asset-next').disabled=state.gallery.length<200;bind('asset-prev',()=>{state.assetOffset=Math.max(0,(state.assetOffset||0)-200);return navigate();});bind('asset-next',()=>{state.assetOffset=(state.assetOffset||0)+200;return navigate();});const visibleSelection=()=>[...grid.querySelectorAll('.asset-select')].filter(x=>!x.closest('.image-card').hidden);$('#asset-all').onclick=()=>{const boxes=visibleSelection();const checked=boxes.some(x=>!x.checked);boxes.forEach(x=>x.checked=checked);};$('#asset-invert').onclick=()=>visibleSelection().forEach(x=>x.checked=!x.checked);for(const action of ['star','unstar','delete']){bind('asset-batch-'+action,async()=>{const ids=[...document.querySelectorAll('.asset-select:checked')].map(x=>x.dataset.asset);if(!ids.length){toast(t('selectImagesFirst'));return;}if(action==='delete'&&!confirm(t('deleteSelectedConfirm')))return;const results=[];for(let i=0;i<ids.length;i+=100){const r=await api('/api/v1/assets/batch',{method:'POST',body:{asset_ids:ids.slice(i,i+100),action}});results.push(...r.results);}const failed=results.filter(x=>x.status==='failed');if(failed.length)toast(t('batchFailed')+' '+failed.length);await navigate();});}}
+ const cards=[...grid.querySelectorAll('.image-card')];$('#gallery-search').oninput=()=>{state.galleryQuery=$('#gallery-search').value;const query=state.galleryQuery.toLowerCase();cards.forEach(card=>card.hidden=!card.textContent.toLowerCase().includes(query));};$('#gallery-sort').onchange=()=>{const order=$('#gallery-sort').value;state.galleryOrder=order;const indexes=cards.map((card,index)=>({card,item:state.gallery[index]}));indexes.sort((a,b)=>order==='name'?a.item.name.localeCompare(b.item.name):order==='oldest'?String(a.item.created_at).localeCompare(String(b.item.created_at)):String(b.item.created_at).localeCompare(String(a.item.created_at)));indexes.forEach(x=>grid.append(x.card));};
+ cards.forEach((card,i)=>{const item=state.gallery[i];if(state.tab==='local'){const star=document.createElement('button');star.textContent=t(item.starred?'unstar':'star');star.setAttribute('aria-pressed',String(item.starred));card.querySelector('.actions').append(star);star.onclick=busy(async()=>{await api('/api/v1/assets/'+item.asset_id+'/star',{method:'PUT',body:{starred:!item.starred}});await navigate();});const label=document.createElement('small');label.textContent=item.origin==='task'?t('taskOrigin')+' · '+(item.job_name||item.job_id):t('origin_'+item.origin);card.querySelector('h3').after(label);const select=document.createElement('input');select.type='checkbox';select.className='asset-select';select.dataset.asset=item.asset_id;select.setAttribute('aria-label',t('selectImage'));card.prepend(select);}if(item.width&&item.height){const dimensions=document.createElement('small');dimensions.textContent=item.width+' × '+item.height;card.querySelector('h3').after(dimensions);}const download=document.createElement('button');download.textContent=t('download');card.querySelector('.actions').append(download);download.onclick=busy(()=>downloadImage(item.url,item.name));if(state.tab==='local'){const edit=document.createElement('button');edit.textContent=t('continueEdit');card.querySelector('.actions').append(edit);edit.onclick=busy(async()=>{const meta=await api('/api/v1/assets/'+item.asset_id+'/source');if(meta.source?.type==='template')await editTemplateSource(meta.source);else toast(t('templateSourceUnavailable'));});}});
+ $('#gallery-search').value=state.galleryQuery||'';$('#gallery-sort').value=state.galleryOrder||'newest';$('#gallery-search').oninput();$('#gallery-sort').onchange();
 }
 async function weatherSettings(){
- const weather=await api('/api/v1/providers/weather');const box=document.createElement('section');box.className='card';box.innerHTML=`<h3>${t('weatherSettings')}</h3><form id="weather-form"><div class="field"><label for="weather-provider">Provider</label><select id="weather-provider"><option value="mock">${t('weatherMock')}</option><option value="open-meteo">Open-Meteo</option></select></div><div class="field"><label for="weather-location">${t('location')}</label><input id="weather-location" required maxlength="120" value="${esc(weather.config.location)}"></div><div class="form-grid">${['latitude','longitude'].map(k=>`<div class="field"><label for="weather-${k}">${t(k)}</label><input id="weather-${k}" required type="number" step="any" min="${k==='latitude'?-90:-180}" max="${k==='latitude'?90:180}" value="${weather.config[k]}"></div>`).join('')}</div><button type="submit" class="primary">${t('save')}</button></form><div id="weather-result"></div>`;$('#main').append(box);$('#weather-provider').value=weather.config.provider;
+ const weather=await api('/api/v1/providers/weather');const box=document.createElement('section');box.className='card';box.innerHTML=`<h3>${t('weatherSettings')}</h3><form id="weather-form"><div class="field"><label for="weather-provider">${t('weatherSettings')}</label><select id="weather-provider"><option value="mock">${t('weatherMock')}</option><option value="open-meteo">Open-Meteo</option></select></div><div class="field"><label for="weather-location">${t('location')}</label><input id="weather-location" required maxlength="120" value="${esc(weather.config.location)}"></div><div class="form-grid weather-coordinates">${['latitude','longitude'].map(k=>`<div class="field"><label for="weather-${k}">${t(k)}</label><input id="weather-${k}" required type="number" step="any" min="${k==='latitude'?-90:-180}" max="${k==='latitude'?90:180}" value="${weather.config[k]}"></div>`).join('')}</div><button type="submit" class="primary">${t('save')}</button></form><div id="weather-result"></div>`;$('#main').append(box);$('#weather-provider').value=weather.config.provider;
  function result(w){$('#weather-result').innerHTML=`<p>${esc(w.current.temperature)} · ${esc(w.current.summary)}</p><p class="hint">${w.current.mock?t('weatherMock'):t('weatherAttribution')}${w.current.stale?' · '+t('stale'):''}</p><h4>${t('forecast')}</h4>${w.forecast.map(x=>`<p>${esc(x.date)} · ${esc(x.summary)} · ${x.minimum_c}–${x.maximum_c}°C · ${x.rain_probability}%</p>`).join('')}`;}
  result(weather);$('#weather-form').onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/settings/weather',{method:'PUT',body:{provider:$('#weather-provider').value,location:$('#weather-location').value,latitude:Number($('#weather-latitude').value),longitude:Number($('#weather-longitude').value)}});result(await api('/api/v1/providers/weather'));toast(t('done'));});
 }
 async function enhanceHistory(){
- const table=document.querySelector('#main table');if(!table)return;table.classList.add('history-table');const heading=document.createElement('th');heading.textContent=t('operation');table.querySelector('thead tr').append(heading);const rows=[...table.querySelectorAll('tbody tr')];const ops=await api('/api/v1/operations');rows.forEach((row,i)=>{const op=ops[i];if(!op)return;const button=document.createElement('button');button.textContent=t('details');const actions=document.createElement('td');actions.className='history-actions';actions.append(button);row.append(actions);button.onclick=busy(async()=>{const current=await api('/api/v1/operations/'+op.operation_id);showModal(`<h2>${t('details')}</h2><p>${t(current.status)} · ${esc(current.action)}</p><p>${esc(current.error?.message||'')}</p><pre style="white-space:pre-wrap;overflow-wrap:anywhere">${esc(JSON.stringify({operation_id:current.operation_id,request_id:current.request_id,created_at:current.created_at,updated_at:current.updated_at,result:current.result},null,2))}</pre>${current.result?.url?'<img id="operation-preview" class="preview" alt="Preview">':''}<div class="modal-actions">${buttons('modal-cancel','cancel')}</div>`);if(current.result?.url)await blobImage($('#operation-preview'),current.result.url);});});}
+ const table=document.querySelector('#main table');if(!table)return;table.classList.add('history-table');const heading=document.createElement('th');heading.textContent=t('operation');table.querySelector('thead tr').append(heading);const rows=[...table.querySelectorAll('tbody tr')];const ops=await api('/api/v1/operations');rows.forEach((row,i)=>{const op=ops[i];if(!op)return;const button=document.createElement('button');button.textContent=t('details');const actions=document.createElement('td');actions.className='history-actions';actions.append(button);row.append(actions);button.onclick=busy(async()=>{const current=await api('/api/v1/operations/'+op.operation_id);showModal(`<h2>${t('details')}</h2><p>${t(current.status)} · ${esc(operationActionLabel(current.action))}</p><p>${esc(operationErrorLabel(current.error)||current.error?.message||'')}</p><pre style="white-space:pre-wrap;overflow-wrap:anywhere">${esc(JSON.stringify({action:current.action,device_id:current.device_id,error_code:current.error?.code,operation_id:current.operation_id,request_id:current.request_id,created_at:current.created_at,updated_at:current.updated_at,result:current.result},null,2))}</pre>${current.result?.url?'<img id="operation-preview" class="preview" alt="Preview">':''}<div class="modal-actions">${buttons('modal-cancel','cancel')}</div>`);if(current.result?.url)await blobImage($('#operation-preview'),current.result.url);});});}
 async function enhanceAutomation(){
  const jobs=await api('/api/v1/jobs');const rows=[...document.querySelectorAll('tbody tr')];rows.forEach((row,i)=>{const job=jobs[i];if(!job)return;const actions=row.querySelector('.row-actions');const run=document.createElement('button');run.textContent=t('runNow');run.disabled=!liveWriteAllowed();run.title=run.disabled?t('readOnlyWarning'):'';actions.append(run);run.onclick=()=>confirmDialog(t('runConfirm'),async()=>{await accepted('/api/v1/jobs/'+job.id+'/run',{});await navigate('history');});if(['template','auto_collage'].includes(job.source.type)){const preview=document.createElement('button');preview.textContent=t('jobPreview');actions.append(preview);preview.onclick=busy(async()=>{const id=await accepted('/api/v1/jobs/'+job.id+'/preview',{});const op=await waitOperation(id);showModal(`<h2>${t('jobPreview')}</h2><img id="job-preview-image" class="preview" alt="Preview"><div class="modal-actions">${buttons('modal-cancel','cancel')}</div>`);await blobImage($('#job-preview-image'),op.result.url);});}});
 }
@@ -139,7 +140,7 @@ function photosLoginDialog(){
 async function photoSourcesPanel(){
  const section=document.createElement('section');section.className='card photo-sources-panel';$('#main').append(section);
  const sources=await api('/api/v1/photo-sources');if(!section.isConnected)return;
- section.innerHTML=`<div class="section-heading"><div><h3>${t('photoSources')}</h3><p class="hint">${t('sourceHint')}</p></div>${buttons('add-photo-source','addSource')}</div><section id="photos-connection" class="photos-connection" aria-label="Synology Photos"></section><div class="source-list">${sources.length?sources.map(s=>`<article class="source-card"><h4>${esc(s.name)}</h4><p class="hint source-identity">${t('sourceIdLabel')}: ${esc(s.id)} · ${t('sourceLocation')}: ${esc(s.location)}</p><p class="hint">${s.people_filter?t('sourceSharedPhotos'):s.kind==='local'?t('sourceLocalOnly'):t('sourceOwnCredentials')}</p><p class="hint">${esc(s.kind)} · ${t(s.enabled?'enabled':'disabled')}${s.people_filter?' · '+t('peopleFilter'):''}${s.orientation?' · '+t({auto:'orientationAuto',landscape:'orientationLandscape',portrait:'orientationPortrait'}[s.orientation]):''}</p><div class="actions"><button data-source-browse="${esc(s.id)}">${t('browse')}</button><button data-source-random="${esc(s.id)}" ${s.enabled?'':'disabled'}>${t('randomPreview')}</button><button data-source-job="${esc(s.id)}">${t('sourceJob')}</button><button data-source-edit="${esc(s.id)}">${t('edit')}</button><button class="danger" data-source-delete="${esc(s.id)}">${t('remove')}</button></div></article>`).join(''):`<p class="hint">${t('noSources')}</p>`}</div><div id="source-browser"></div>`;
+ section.innerHTML=`<div class="section-heading"><div><h3>${t('photoSources')}</h3><p class="hint">${t('sourceHint')}</p></div>${buttons('add-photo-source','addSource')}</div><section id="photos-connection" class="photos-connection" aria-label="Synology Photos"></section><div class="source-list">${sources.length?sources.map(s=>`<article class="source-card"><h4>${esc(s.name)}</h4><p class="hint source-identity">${t('sourceIdLabel')}: ${esc(s.id)} · ${t('sourceLocation')}: ${esc(s.location)}</p><p class="hint">${s.kind==='synology-photos'?t('sourcePhotosAPI'):t('sourceOwnCredentials')}</p><p class="hint">${esc(s.kind==='synology-photos'?'Synology Photos':s.kind)} · ${t(s.enabled?'enabled':'disabled')}${s.people_filter?' · '+t('peopleFilter'):''}${s.orientation?' · '+t({auto:'orientationAuto',landscape:'orientationLandscape',portrait:'orientationPortrait'}[s.orientation]):''}</p><div class="actions"><button data-source-browse="${esc(s.id)}">${t('browse')}</button><button data-source-random="${esc(s.id)}" ${s.enabled?'':'disabled'}>${t('randomPreview')}</button><button data-source-job="${esc(s.id)}">${t('sourceJob')}</button><button data-source-edit="${esc(s.id)}">${t('edit')}</button><button class="danger" data-source-delete="${esc(s.id)}">${t('remove')}</button></div></article>`).join(''):`<p class="hint">${t('noSources')}</p>`}</div><div id="source-browser"></div>`;
  await photosConnectionPanel();
  bind('add-photo-source',()=>photoSourceForm());
  section.querySelectorAll('[data-source-edit]').forEach(b=>b.onclick=()=>photoSourceForm(sources.find(s=>s.id===b.dataset.sourceEdit)));
@@ -149,19 +150,19 @@ async function photoSourcesPanel(){
  section.querySelectorAll('[data-source-job]').forEach(b=>b.onclick=()=>sourceJobForm(b.dataset.sourceJob));
 }
 async function photoSourceForm(source=null){
- showModal(`<h2>${t(source?'edit':'addSource')}</h2><p class="notice">${t('sourceIndependentHelp')}</p><form id="photo-source-form"><div class="field"><label for="source-id">ID</label><input id="source-id" pattern="[a-z0-9-]{1,60}" required value="${esc(source?.id||'')}" ${source?'readonly':''}></div><div class="field"><label for="source-name">${t('name')}</label><input id="source-name" required maxlength="120" value="${esc(source?.name||'')}"></div><div class="field"><label for="source-kind">${t('sourceKind')}</label><select id="source-kind"><option value="local">${t('nasDirectory')}</option><option value="webdav">WebDAV</option><option value="google-drive">Google Drive</option><option value="alipan">阿里云盘 / AliPan</option><option value="baidu">百度网盘 / Baidu</option></select></div><div class="field"><label for="source-location">${t('sourceLocation')}</label><input id="source-location" required maxlength="2048" value="${esc(source?.location||'.')}"><p class="hint">${t('sourceLocationHint')}</p></div><div class="field"><label for="source-credential">${t('sourceCredential')}</label><input id="source-credential" pattern="FRAME_FLOW_SOURCE_[A-Z0-9_]+" value="${esc(source?.credential_env||'')}" placeholder="FRAME_FLOW_SOURCE_CLOUD"><p class="hint">${t('sourceCredentialHint')}</p></div><div class="field"><label for="source-orientation">${t('photoOrientation')}</label><select id="source-orientation">${source&&!source.orientation?`<option value="">${t('orientationLegacy')}</option>`:''}<option value="auto">${t('orientationAuto')}</option><option value="landscape">${t('orientationLandscape')}</option><option value="portrait">${t('orientationPortrait')}</option></select><p class="hint">${t('orientationHint')}</p></div><div class="field"><label class="check-row"><input id="source-organized" type="checkbox" ${source?.organized_only?'checked':''}>${t('organizedPhotos')}</label><label class="check-row"><input id="source-caption" type="checkbox" ${source?.folder_caption?'checked':''}>${t('folderCaption')}</label><label class="check-row"><input id="source-synology-previews" type="checkbox" ${source?.synology_previews?'checked':''}>${t('synologyPreviews')}</label><p class="hint">${t('folderCaptionHint')}</p></div><div class="field"><label class="check-row"><input id="source-people-filter" type="checkbox" ${source?.people_filter?'checked':''}>${t('peopleFilter')}</label><p class="hint">${t('peopleHint')}</p><button id="source-people-load" type="button">${t('choosePeople')}</button><div id="source-people-panel"><p class="hint">${t('peopleSelected')}${(source?.person_ids||[]).length}</p></div><label for="source-person-match">${t('personMatch')}</label><select id="source-person-match"><option value="any">${t('personAny')}</option><option value="all">${t('personAll')}</option></select></div><div class="field"><label class="check-row"><input id="source-recursive" type="checkbox" ${source?.recursive===false?'':'checked'}>${t('sourceRecursive')}</label><label class="check-row"><input id="source-enabled" type="checkbox" ${source?.enabled===false?'':'checked'}>${t('enabled')}</label></div><div class="modal-actions">${buttons('modal-cancel','cancel')}<button type="submit" class="primary">${t('save')}</button></div></form>`);
- $('#source-orientation').value=source?(source.orientation||''):'auto';const selectedPeople=new Set(source?.person_ids||[]);$('#source-person-match').value=source?.person_match||'any';$('#source-people-load').onclick=busy(async()=>{await photosPeoplePicker(selectedPeople);});$('#source-kind').value=source?.kind||'local';const update=()=>{const dav=$('#source-kind').value!=='local';$('#source-orientation').disabled=dav;$('#source-credential').disabled=!dav;$('#source-credential').closest('.field').hidden=$('#source-kind').value!=='webdav';const oauth=$('#source-oauth');if(oauth)oauth.closest('.field').hidden=!['google-drive','alipan','baidu'].includes($('#source-kind').value);const quality=$('#source-local-quality');if(quality)quality.hidden=dav;$('#source-recursive').disabled=$('#source-kind').value==='webdav';$('#source-synology-previews').disabled=dav;$('#source-organized').disabled=dav;$('#source-caption').disabled=dav;$('#source-people-filter').disabled=dav;$('#source-people-load').disabled=dav;};addPhotoQualityFields(source);update();$('#source-kind').onchange=update;$('#source-people-space').onchange=()=>{selectedPeople.clear();$('#source-people-panel').innerHTML='';};
- $('#photo-source-form').onsubmit=busy(async e=>{e.preventDefault();const oauth=$('#source-oauth').value;const sourceId=$('#source-id').value;const native=['google-drive','alipan','baidu'].includes($('#source-kind').value);if(oauth&&native)JSON.parse(oauth);const dav=$('#source-kind').value!=='local';await api('/api/v1/photo-sources/'+$('#source-id').value,{method:'PUT',body:{name:$('#source-name').value,kind:$('#source-kind').value,location:$('#source-location').value,recursive:$('#source-kind').value!=='webdav'&&$('#source-recursive').checked,synology_previews:!dav&&$('#source-synology-previews').checked,catalog_limit:$('#source-organized').checked?100000:(source?.catalog_limit||10000),organized_only:!dav&&$('#source-organized').checked,folder_caption:!dav&&$('#source-caption').checked,orientation:dav?null:($('#source-orientation').value||null),people_filter:!dav&&$('#source-people-filter').checked,person_ids:[...selectedPeople],person_match:$('#source-person-match').value,people_space:$('#source-people-space').value,minimum_sharpness:Number($('#source-sharpness').value),minimum_brightness:Number($('#source-bright-min').value),maximum_brightness:Number($('#source-bright-max').value),avoid_duplicates:$('#source-dedup').checked,enabled:$('#source-enabled').checked,credential_env:dav?($('#source-credential').value||null):null}});if(oauth&&native){$('#source-oauth').value='';await api('/api/v1/photo-sources/'+sourceId+'/credentials',{method:'PUT',body:{key:oauth}});}$('#modal').close();await navigate('photo-sources');});
+ showModal(`<h2>${t(source?'edit':'addSource')}</h2><p class="notice">${t('sourceIndependentHelp')}</p><form id="photo-source-form"><input id="source-id" type="hidden" value="${esc(source?.id||'photos-'+clientUUID())}"><div class="field"><label for="source-name">${t('name')}</label><input id="source-name" required maxlength="120" value="${esc(source?.name||'')}"></div><div class="field" ${!source||source.kind==='synology-photos'?'hidden':''}><label for="source-kind">${t('sourceKind')}</label><select id="source-kind"><option value="synology-photos">${t('synologyAPISource')}</option><option value="webdav">WebDAV</option><option value="google-drive">Google Drive</option><option value="alipan">阿里云盘 / AliPan</option><option value="baidu">百度网盘 / Baidu</option></select></div><div class="field"><label for="source-location">${t('sourceLocation')}</label><input id="source-location" required maxlength="2048" value="${esc(source?.location||'.')}"><p class="hint">${t('sourceLocationHint')}</p></div><div class="field" id="source-nas-root-field"><label for="source-nas-root">${tr('NAS 原照片根目录（仅用于显示路径）','NAS original root (display only)')}</label><input id="source-nas-root" pattern="/.*" maxlength="2048" placeholder="/volume1/photo" value="${esc(source?.nas_root_path||'')}"><p class="hint">${tr('共享空间通常为 /volume1/photo，请填写实际 NAS 根目录；留空时显示 Photos 空间内路径。','Enter the actual NAS root; shared space is commonly /volume1/photo. Blank shows the path within Photos.')}</p></div><div class="field"><label for="source-credential">${t('sourceCredential')}</label><input id="source-credential" pattern="FRAME_FLOW_SOURCE_[A-Z0-9_]+" value="${esc(source?.credential_env||'')}" placeholder="FRAME_FLOW_SOURCE_CLOUD"><p class="hint">${t('sourceCredentialHint')}</p></div><div class="field"><label for="source-orientation">${t('photoOrientation')}</label><select id="source-orientation">${source&&!source.orientation?`<option value="">${t('orientationLegacy')}</option>`:''}<option value="auto">${t('orientationAuto')}</option><option value="landscape">${t('orientationLandscape')}</option><option value="portrait">${t('orientationPortrait')}</option></select><p class="hint">${t('orientationHint')}</p></div><div class="field"><label class="check-row"><input id="source-organized" type="checkbox" ${source?.organized_only?'checked':''}>${t('organizedPhotos')}</label><label class="check-row"><input id="source-caption" type="checkbox" ${!source||source.folder_caption?'checked':''}>${t('folderCaption')}</label><label hidden><input id="source-synology-previews" type="checkbox" disabled></label><p class="hint">${t('folderCaptionHint')}</p></div><div class="field"><label class="check-row"><input id="source-people-filter" type="checkbox" ${source?.people_filter?'checked':''}>${t('peopleFilter')}</label><p class="hint">${t('peopleHint')}</p><button id="source-people-load" type="button">${t('choosePeople')}</button><div id="source-people-panel"><p class="hint">${t('peopleSelected')}${(source?.person_ids||[]).length}</p></div><label for="source-person-match">${t('personMatch')}</label><select id="source-person-match"><option value="any">${t('personAny')}</option><option value="all">${t('personAll')}</option></select></div><div class="field"><label class="check-row"><input id="source-recursive" type="checkbox" ${source?.recursive===false?'':'checked'}>${t('sourceRecursive')}</label><label class="check-row"><input id="source-enabled" type="checkbox" ${source?.enabled===false?'':'checked'}>${t('enabled')}</label></div><div class="modal-actions">${buttons('modal-cancel','cancel')}<button type="submit" class="primary">${t('save')}</button></div></form>`);
+ $('#source-orientation').value=source?(source.orientation||''):'auto';const selectedPeople=new Set(source?.person_ids||[]);$('#source-person-match').value=source?.person_match||'any';$('#source-people-load').onclick=busy(async()=>{await photosPeoplePicker(selectedPeople);});$('#source-kind').value=source?.kind||'synology-photos';const update=()=>{const photosAPI=$('#source-kind').value==='synology-photos';$('#source-nas-root-field').hidden=!photosAPI;$('#source-location').labels[0].textContent=photosAPI?tr('照片目录','Photo folder'):t('sourceLocation');$('#source-location').nextElementSibling.textContent=photosAPI?tr('填写所选空间内的目录路径，. 表示整个空间。按需获取 XL 预览图，不下载原图。','Folder path within the selected space; . means the whole space. Downloads XL previews on demand, not originals.'):t('sourceLocationHint');const dav=!['local','synology-photos'].includes($('#source-kind').value);$('#source-orientation').disabled=dav;$('#source-credential').disabled=!dav;$('#source-credential').closest('.field').hidden=$('#source-kind').value!=='webdav';const oauth=$('#source-oauth');if(oauth)oauth.closest('.field').hidden=!['google-drive','alipan','baidu'].includes($('#source-kind').value);const quality=$('#source-local-quality');if(quality)quality.hidden=dav;$('#source-recursive').disabled=$('#source-kind').value==='webdav';$('#source-synology-previews').disabled=$('#source-kind').value!=='local';$('#source-organized').disabled=dav;$('#source-caption').disabled=dav;$('#source-people-filter').disabled=dav;$('#source-people-load').disabled=dav;};addPhotoQualityFields(source);$('#source-location').closest('.field').before($('#source-people-space').closest('.field'));update();$('#source-kind').onchange=update;$('#source-people-space').onchange=()=>{selectedPeople.clear();$('#source-people-panel').innerHTML='';};
+ $('#photo-source-form').onsubmit=busy(async e=>{e.preventDefault();const oauth=$('#source-oauth').value;const sourceId=$('#source-id').value;const native=['google-drive','alipan','baidu'].includes($('#source-kind').value);if(oauth&&native)JSON.parse(oauth);const dav=!['local','synology-photos'].includes($('#source-kind').value);await api('/api/v1/photo-sources/'+$('#source-id').value,{method:'PUT',body:{name:$('#source-name').value,kind:$('#source-kind').value,location:$('#source-location').value,nas_root_path:$('#source-nas-root').value||null,recursive:$('#source-kind').value!=='webdav'&&$('#source-recursive').checked,synology_previews:false,catalog_limit:$('#source-organized').checked?100000:(source?.catalog_limit||10000),organized_only:!dav&&$('#source-organized').checked,folder_caption:!dav&&$('#source-caption').checked,orientation:dav?null:($('#source-orientation').value||null),people_filter:!dav&&$('#source-people-filter').checked,person_ids:[...selectedPeople],person_match:$('#source-person-match').value,people_space:$('#source-people-space').value,minimum_short_edge:Number($('#source-min-short').value),minimum_long_edge:Number($('#source-min-long').value),minimum_sharpness:Number($('#source-sharpness').value),minimum_brightness:Number($('#source-bright-min').value),maximum_brightness:Number($('#source-bright-max').value),avoid_duplicates:$('#source-dedup').checked,enabled:$('#source-enabled').checked,credential_env:dav?($('#source-credential').value||null):null}});if(oauth&&native){$('#source-oauth').value='';await api('/api/v1/photo-sources/'+sourceId+'/credentials',{method:'PUT',body:{key:oauth}});}$('#modal').close();await navigate('photo-sources');});
 }
 async function browseSource(id,offset=0,refresh=false){
  const result=await api('/api/v1/photo-sources/'+id+'/images?device_id='+encodeURIComponent(state.device)+'&offset='+offset+'&limit=50&refresh='+refresh);const box=$('#source-browser');if(!box)return;
- box.innerHTML=`<h4>${t('sourceImages')} · ${result.total}${result.total>=result.catalog_limit?' (limit)':''}</h4><p class="hint">${t('sourceBrowseHint')}</p><div class="source-items">${result.items.map((x,i)=>`<button data-source-item="${i}">${esc(x.name)}${x.width?`<small>${x.width} × ${x.height}</small>`:''}${x.caption?`<small>${esc([x.caption.title,x.caption.date,x.caption.place].filter(Boolean).join(' · '))}</small>`:''}</button>`).join('')||t('noSources')}</div><div class="actions"><button id="source-prev" ${offset?'':'disabled'}>${t('previousPage')}</button><button id="source-next" ${offset+result.items.length<result.total?'':'disabled'}>${t('nextPage')}</button>${buttons('source-refresh','refresh')}</div>`;
+ box.innerHTML=`<h4>${t('sourceImages')} · ${result.total}${result.total>=result.catalog_limit?' (limit)':''}</h4><p class="hint">${t('sourceBrowseHint')}</p><div class="source-items">${result.items.map((x,i)=>`<button data-source-item="${i}">${esc(x.name)}${x.width?`<small>${x.width} × ${x.height}</small>`:''}${x.caption?`<small>${esc([x.caption.date,x.caption.people,x.caption.title,x.caption.place,x.caption.filename].filter(Boolean).join(' · '))}</small>`:''}</button>`).join('')||t('noSourcePhotos')}</div><div class="actions"><button id="source-prev" ${offset?'':'disabled'}>${t('previousPage')}</button><button id="source-next" ${offset+result.items.length<result.total?'':'disabled'}>${t('nextPage')}</button>${buttons('source-refresh','refresh')}</div>`;
  box.querySelectorAll('[data-source-item]').forEach(b=>b.onclick=busy(()=>previewSource(id,result.items[Number(b.dataset.sourceItem)].id)));bind('source-prev',()=>browseSource(id,Math.max(0,offset-50)));bind('source-next',()=>browseSource(id,offset+50));bind('source-refresh',()=>browseSource(id,0,true));
 }
 async function previewSource(id,item_id=null){
  const acceptedResult=await api('/api/v1/devices/'+state.device+'/upload',{method:'POST',body:{type:'photo_source',source_id:id,item_id,fit:'contain',profile:'color'},headers:{'Idempotency-Key':clientUUID()}});const op=await waitOperation(acceptedResult.operation_id);
  showModal(`<h2>${t('preview')}</h2><img id="source-preview" class="preview" alt="${t('preview')}"><p class="hint">${t('sourcePreviewHint')}</p><div class="modal-actions">${buttons('modal-cancel','cancel')}${buttons('source-display','display',true)}</div>`);await blobImage($('#source-preview'),op.result.url);$('#source-display').disabled=!liveWriteAllowed();bind('source-display',()=>displayDialog({type:'image',asset_id:op.result.asset_id}));
 }
-function sourceJobForm(id){
- showModal(`<h2>${t('sourceJob')}</h2><form id="source-job-form"><div class="field"><label for="source-job-name">${t('name')}</label><input id="source-job-name" required maxlength="120" value="${t('randomPhoto')}"></div><div class="field"><label for="source-job-cron">Cron · Asia/Shanghai</label><input id="source-job-cron" required value="0 8 * * *"><p class="hint">${t('sourceJobHint')}</p></div><div class="field"><label class="check-row"><input id="source-job-enabled" type="checkbox">${t('enabled')}</label></div><p class="hint">${t('cloudKeepLatest')}</p><div class="modal-actions">${buttons('modal-cancel','cancel')}<button class="primary" type="submit">${t('save')}</button></div></form>`);$('#source-job-form').onsubmit=busy(async e=>{e.preventDefault();await api('/api/v1/jobs',{method:'POST',body:{name:$('#source-job-name').value,device_id:state.device,enabled:$('#source-job-enabled').checked,cleanup_unstarred:false,schedule:{type:'cron',cron:$('#source-job-cron').value},source:{type:'photo_source',source_id:id,fit:'contain',profile:'color'}}});$('#modal').close();await navigate('automation');});
+async function sourceJobForm(id){
+ await jobEditor({name:t('randomPhoto'),device_id:state.device,enabled:false,schedule:{type:'interval',interval_minutes:120},source:{type:'photo_source',source_id:id,fit:'contain',profile:'color'},display_duration:0,restore_previous:false,priority:50});
 }

pigway_frame_flow/web/index.html

@@ -1,3 +1,3 @@
 <!doctype html>
-<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><meta name="color-scheme" content="light dark"><title>Pigway Frame Flow</title><link rel="stylesheet" href="/ui/style.css"></head>
-<body><aside class="sidebar"><a class="brand" href="/"><span class="brand-icon">F<span>↗</span></span><span>Frame Flow<small>Pigway · Smart Frame Automation</small></span></a><nav id="nav"></nav><div class="sidebar-bottom"><small>Version 0.1.6</small></div></aside><div class="workspace"><header><div><span class="eyebrow">PIGWAY FRAME FLOW</span><h1 id="page-title"></h1></div><div class="toolbar"><select id="device" aria-label="Device"></select><button id="lang" class="icon-button" aria-label="Change language">EN</button><button id="theme" class="icon-button" aria-label="Change theme">◐</button></div></header><main id="main"></main><footer id="footer"></footer></div><div id="toast" role="status" aria-live="polite"></div><dialog id="modal"><div id="modal-content"></div></dialog><script src="/ui/i18n.js"></script><script src="/ui/features.js"></script><script src="/ui/extensions.js"></script><script src="/ui/app.js"></script></body></html>
+<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><meta name="color-scheme" content="light dark"><title>PIGWay Frame Flow</title><link rel="stylesheet" href="/ui/style.css"></head>
+<body><aside class="sidebar"><a class="brand" href="/"><span>PIGWay Frame Flow<small>Smart Frame Automation</small></span></a><nav id="nav"></nav><div class="sidebar-bottom"><small>Version 0.1.17</small></div></aside><div class="workspace"><header><div><span class="eyebrow">PIGWay Frame Flow</span><h1 id="page-title"></h1></div><div class="toolbar"><select id="device" aria-label="Device"></select><button id="lang" class="icon-button" aria-label="Change language">EN</button><button id="theme" class="icon-button" aria-label="Change theme">◐</button></div></header><main id="main"></main><footer id="footer"></footer></div><div id="toast" role="status" aria-live="polite"></div><dialog id="modal"><div id="modal-content"></div></dialog><script src="/ui/i18n.js?v=photo-quality-v0117"></script><script src="/ui/features.js?v=photo-quality-v0117"></script><script src="/ui/extensions.js?v=photo-quality-v0117"></script><script src="/ui/app.js?v=photo-quality-v0117"></script></body></html>

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pigway-frame-flow"
-version = "0.1.6"
+version = "0.1.17"
 requires-python = ">=3.12"
 dependencies = ["paho-mqtt==2.1.0", "python-dateutil==2.9.0.post0", "fastapi==0.142.2", "uvicorn==0.54.0", "pillow==12.3.0", "requests==2.34.2", "croniter==6.2.4", "python-multipart==0.0.32", "pyyaml==6.0.3"]
 [project.optional-dependencies]

scripts/migrate-photos-api.py

@@ -0,0 +1,83 @@
+"""Offline, explicit local-to-Photos-API source conversion; defaults to dry run."""
+
+import argparse
+import json
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pigway_frame_flow.providers.photo_sources import PhotoSourceInput
+
+
+def convert(database, source_ids, *, apply=False):
+    connection = sqlite3.connect(f"file:{database}?mode=rw", uri=True)
+    try:
+        updates = []
+        for source_id in source_ids:
+            key = "photo_source:" + source_id
+            row = connection.execute(
+                "SELECT payload FROM app_config WHERE key=?", (key,)
+            ).fetchone()
+            if not row:
+                raise ValueError("Source not found: " + source_id)
+            source = PhotoSourceInput.model_validate_json(row[0])
+            if source.kind != "local":
+                raise ValueError(
+                    "Only explicitly selected local sources can be converted"
+                )
+            location = source.location.strip("/")
+            if (
+                source.location.startswith("/")
+                or "\\" in location
+                or ".." in location.split("/")
+            ):
+                raise ValueError(
+                    "Review the source's relative Photos folder path first"
+                )
+            payload = source.model_copy(
+                update={"kind": "synology-photos", "synology_previews": False}
+            )
+            updates.append((payload.model_dump_json(), key))
+        backup = None
+        if apply:
+            backup = database.with_name(
+                database.name
+                + ".before-photos-api-"
+                + datetime.now(UTC).strftime("%Y%m%dT%H%M%S%fZ")
+            )
+            with sqlite3.connect(backup) as snapshot:
+                connection.backup(snapshot)
+            backup.chmod(0o600)
+            with connection:
+                connection.executemany(
+                    "UPDATE app_config SET payload=? WHERE key=?", updates
+                )
+        return {
+            "applied": apply,
+            "sources": source_ids,
+            "backup": str(backup) if backup else None,
+        }
+    finally:
+        connection.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--database", type=Path, required=True)
+    parser.add_argument("--source", action="append", required=True)
+    parser.add_argument("--apply", action="store_true")
+    parser.add_argument(
+        "--service-stopped",
+        action="store_true",
+        help="Confirm the target service is stopped before changing its database",
+    )
+    args = parser.parse_args()
+    if args.apply and not args.service_stopped:
+        parser.error(
+            "Stop the target service and pass --service-stopped before applying"
+        )
+    print(json.dumps(convert(args.database, args.source, apply=args.apply), indent=2))
+
+
+if __name__ == "__main__":
+    main()

scripts/production-deploy.py

@@ -70,6 +70,13 @@ class Deploy:
         return json.loads(self.run("inspect", name).stdout)[0]
 
     def settings(self):
+        if any(
+            self.env.get(key, "").startswith("/volume2/docker/pigway-frame-flow")
+            for key in ("PROD_DATA_DIR", "PROD_CONFIG_DIR")
+        ):
+            raise ValueError(
+                "NAS Frame deployment is retired; target the Ubuntu Server"
+            )
         missing = [key for key in REQUIRED if not self.env.get(key)]
         if missing:
             raise ValueError("Missing Variables: " + ", ".join(missing))
@@ -118,20 +125,9 @@ class Deploy:
                 or not m.get("RW")
             ):
                 raise ValueError("Production mount mismatch: " + key)
-        photos = self.env.get("PROD_PHOTOS_DIR")
-        if "/photos" in mounts and (
-            not photos
-            or mounts["/photos"]["Source"] != photos
-            or mounts["/photos"]["RW"]
-        ):
-            raise ValueError(
-                "Confirm PROD_PHOTOS_DIR for the existing read-only photo mount"
-            )
-        if photos and "/photos" not in mounts:
-            raise ValueError(
-                "Configured photos directory does not match current container"
-            )
-        if set(mounts) != {"/data", "/config"} | ({"/photos"} if photos else set()):
+        if self.env.get("PROD_PHOTOS_DIR") or "/photos" in mounts:
+            raise ValueError("Filesystem photo mounts are retired; use the Photos API")
+        if set(mounts) != {"/data", "/config"}:
             raise ValueError("Unrecognized persistent mount; review before adopting CD")
         bindings = old["HostConfig"].get("PortBindings", {}).get("18787/tcp")
         if bindings != [
@@ -180,16 +176,6 @@ class Deploy:
             )
         ]
         service["group_add"] = old["HostConfig"].get("GroupAdd") or []
-        if photos:
-            service["volumes"].append(
-                {
-                    "type": "bind",
-                    "source": photos,
-                    "target": "/photos",
-                    "read_only": True,
-                    "bind": {"create_host_path": False},
-                }
-            )
         # Adoption must preserve runtime constraints, not silently change them.
         if (
             old["Config"]["User"] != service["user"]

scripts/server-release.py

@@ -0,0 +1,255 @@
+"""Release a verified source bundle on the Ubuntu T7 host; never write to frames."""
+
+import datetime
+import fcntl
+import hashlib
+import json
+import os
+import re
+import shutil
+import sqlite3
+import subprocess
+import time
+import urllib.request
+from pathlib import Path
+
+APP = Path("/srv/pigway/apps/pigway-frame-flow")
+RECOVERY = Path("/srv/pigway/recovery/frame-flow")
+CONTAINER = "pigway-frame-flow"
+ORIGIN = "http://192.0.2.10:81"
+
+
+def run(*args):
+    return subprocess.check_output(args, text=True, timeout=600).strip()
+
+
+def inspect():
+    return json.loads(run("docker", "inspect", CONTAINER))[0]
+
+
+def archive_staging(backup, ctx):
+    # These are retired Frame-only inputs, never shared console migration files.
+    names = [
+        "frame-schedule-ui",
+        "frame-photos-ui",
+        "frame-final-status.sh",
+        "frame-compose.candidate.private.json",
+        "frame-fresh-compose.private.json",
+        "frame-image.tar",
+        "frame-prepare.sh",
+        "frame-nfs-setup.sh",
+        "frame.unit",
+        "compose.ubuntu-photos-api.yml",
+    ]
+    archive = backup / "retired-frame-staging"
+    archive.mkdir(mode=0o700)
+    moved = []
+    for name in names:
+        source = ctx.parent / name
+        if source.exists():
+            assert not source.is_symlink(), name
+            source.rename(archive / name)
+            moved.append(name)
+    for p in archive.rglob("*"):
+        if not p.is_symlink():
+            p.chmod(0o700 if p.is_dir() else 0o600)
+    # Remove only disposable aliases, preserving every recovery reference and image.
+    references = "\n".join(
+        p.read_text(errors="replace")
+        for p in RECOVERY.rglob("*")
+        if p.is_file() and p.suffix in {".json", ".txt"}
+    )
+    removed = []
+    for tag in [
+        "pigway-frame-flow:history-ui-local-base",
+        "pigway-frame-flow:final-audit-local-base",
+        "pigway-frame-flow:0.1.9-5d2171b9be3e",
+    ]:
+        tags = run(
+            "docker", "image", "ls", "--format", "{{.Repository}}:{{.Tag}}"
+        ).splitlines()
+        if (
+            tag in tags
+            and tag not in references
+            and not run("docker", "ps", "-aq", "--filter", "ancestor=" + tag)
+        ):
+            run("docker", "image", "rm", tag)
+            removed.append(tag)
+    return {
+        "archived_frame_inputs": moved,
+        "removed_temporary_aliases": removed,
+        "shared_inputs_and_recovery_preserved": True,
+    }
+
+
+def wait_ready():
+    for attempt in range(30):
+        try:
+            with urllib.request.urlopen(ORIGIN + "/ready", timeout=4) as r:
+                assert json.load(r)["status"] == "ready"
+            break
+        except Exception:
+            if attempt == 29:
+                raise
+            time.sleep(2)
+
+
+def verify_runtime(commit):
+    c = inspect()
+    env = dict(s.split("=", 1) for s in c["Config"]["Env"])
+    assert env["KOKONNA_MOCK"] == "false"
+    assert env["KOKONNA_WRITE_ENABLED"] == "true"
+    assert env["BUILD_COMMIT"] == commit
+    assert c["State"]["Running"]
+    assert c["Config"]["User"] == "10333:10333"
+    assert c["HostConfig"]["ReadonlyRootfs"]
+    assert set(c["HostConfig"]["CapDrop"]) == {"ALL"}
+    assert {m["Destination"] for m in c["Mounts"]} == {"/data", "/config"}
+    for mount in c["Mounts"]:
+        assert Path(mount["Source"]).resolve() == APP / mount["Destination"][1:]
+    return c
+
+
+def main():
+    assert os.geteuid() == 0, "Run with sudo on the Ubuntu Server"
+    os.umask(0o077)
+    run("/usr/local/libexec/pigway-guard-mount")
+    assert run("findmnt", "-n", "-o", "UUID", "/srv/pigway") == (
+        "00000000-0000-4000-8000-000000000001"
+    )
+    with (RECOVERY / ".release.lock").open("a") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        release(lock)
+
+
+def release(lock):
+    ctx = Path(__file__).resolve().parent.parent
+    assert ctx.parent == Path("/srv/pigway/migration-inbox")
+    commit = (ctx / "RELEASE_COMMIT").read_text().strip()
+    assert re.fullmatch("[0-9a-f]{40}", commit)
+    hashes = json.loads((ctx / "RELEASE_HASHES.json").read_text())
+    for name, expected in hashes.items():
+        p = (ctx / name).resolve()
+        assert p.is_relative_to(ctx)
+        assert hashlib.sha256(p.read_bytes()).hexdigest() == expected, name
+    before = inspect()
+    old_env = dict(s.split("=", 1) for s in before["Config"]["Env"])
+    verify_runtime(old_env["BUILD_COMMIT"])
+    assert run("docker", "exec", CONTAINER, "cat", "/app/requirements.lock") == (
+        (ctx / "requirements.lock").read_text().strip()
+    ), "Dependencies differ; full build required"
+    stamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    backup = RECOVERY / ("release-" + stamp + "-" + commit[:12])
+    backup.mkdir(mode=0o700)
+    shutil.copy2(APP / "compose.json", backup / "compose.before.json")
+    shutil.copytree(APP / "config", backup / "config")
+    with sqlite3.connect(
+        "file:" + str(APP / "data/frameflow.db") + "?mode=ro", uri=True
+    ) as src:
+        with sqlite3.connect(backup / "frameflow.before.db") as dst:
+            src.backup(dst)
+            assert dst.execute("pragma quick_check").fetchone()[0] == "ok"
+    base = "pigway-frame-flow:release-base-" + commit[:12]
+    run("docker", "image", "tag", before["Image"], base)
+    image = "pigway-frame-flow:0.1.17-" + commit[:12]
+    try:
+        run(
+            "docker",
+            "build",
+            "--pull=false",
+            "--network=none",
+            "-f",
+            str(ctx / "deploy/Dockerfile.runtime-update"),
+            "--build-arg",
+            "BASE_IMAGE=" + base,
+            "--build-arg",
+            "BUILD_COMMIT=" + commit,
+            "--build-arg",
+            "BUILD_TIME=" + stamp,
+            "-t",
+            image,
+            str(ctx),
+        )
+    finally:
+        run("docker", "image", "rm", base)
+    compose = json.loads((APP / "compose.json").read_text())
+    service = compose["services"][CONTAINER]
+    service["image"] = image
+    service["environment"]["BUILD_COMMIT"] = commit
+    service["environment"]["BUILD_TIME"] = stamp
+    changed = False
+    try:
+        changed = True
+        (APP / "compose.json").write_text(json.dumps(compose, indent=2) + "\n")
+        print("Restarting Frame Flow; checking " + ORIGIN + "/ready", flush=True)
+        run("systemctl", "restart", "pigway-frame-flow.service")
+        wait_ready()
+        current = verify_runtime(commit)
+        assert current["Image"] == run(
+            "docker", "image", "inspect", "--format", "{{.Id}}", image
+        )
+        # Verify all deployed project files, not just a version string or an image tag.
+        project_hashes = {
+            n: h
+            for n, h in hashes.items()
+            if n.startswith(("pigway_frame_flow/", "vendor/"))
+            or n == "requirements.lock"
+        }
+        code = 'import hashlib,json,pathlib,sys; h=json.load(sys.stdin); assert all(hashlib.sha256((pathlib.Path("/app")/n).read_bytes()).hexdigest()==v for n,v in h.items())'
+        subprocess.run(
+            ["docker", "exec", "-i", CONTAINER, "python", "-c", code],
+            input=json.dumps(project_hashes),
+            text=True,
+            check=True,
+            timeout=60,
+        )
+        for name in [
+            "app.js",
+            "features.js",
+            "extensions.js",
+            "i18n.js",
+            "index.html",
+            "style.css",
+        ]:
+            url = ORIGIN + "/" + ("" if name == "index.html" else "ui/" + name)
+            with urllib.request.urlopen(url, timeout=10) as response:
+                assert (
+                    response.read()
+                    == (ctx / "pigway_frame_flow/web" / name).read_bytes()
+                )
+        run("systemctl", "is-active", "pigway-frame-flow.service")
+    except BaseException:
+        print("Release verification failed; restoring previous Compose", flush=True)
+        if changed:
+            shutil.copy2(backup / "compose.before.json", APP / "compose.json")
+            run("systemctl", "restart", "pigway-frame-flow.service")
+        raise
+    shutil.copy2(APP / "compose.json", RECOVERY / "compose.json")
+    (RECOVERY / "image.txt").write_text(image + "\n")
+    shutil.copy2(ctx / "source.tar.gz", backup / "source.tar.gz")
+    cleanup = archive_staging(backup, ctx)
+    receipt = {
+        "result": "PASS",
+        "commit": commit,
+        "image": image,
+        "image_id": current["Image"],
+        "backup": str(backup),
+        "mock": False,
+        "write_enabled": True,
+        "checked_at": stamp,
+        "cleanup": cleanup,
+    }
+    output = APP / "release-verification.json"
+    output.write_text(json.dumps(receipt, indent=2) + "\n")
+    owner = ctx.stat()
+    os.chown(output, owner.st_uid, owner.st_gid)
+    shutil.copy2(output, backup / "release-verification.json")
+    public_receipt = ctx.parent / "frame-release-verification.json"
+    shutil.copy2(output, public_receipt)
+    os.chown(public_receipt, owner.st_uid, owner.st_gid)
+    shutil.rmtree(ctx)
+    print(json.dumps(receipt, indent=2))
+
+
+if __name__ == "__main__":
+    main()

scripts/ui-copy-audit.cjs

@@ -0,0 +1,5 @@
+/* Copy must describe actual storage targets and actions; run against isolated Mock only. */
+const assert=require('assert'),fs=require('fs'),vm=require('vm'),{chromium}=require('playwright');
+const context={};context.window=context;vm.createContext(context);vm.runInContext(fs.readFileSync('pigway_frame_flow/web/i18n.js','utf8'),context);
+for(const file of ['app.js','features.js','extensions.js'])for(const match of fs.readFileSync('pigway_frame_flow/web/'+file,'utf8').matchAll(/\bt\('([^']+)'\)/g))for(const lang of ['zh','en'])assert(context.MESSAGES[lang][match[1]],`${file}: missing ${lang}.${match[1]}`);
+(async()=>{const b=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});try{const p=await b.newPage();let deletes=0;await p.route('**/api/v1/assets?*',r=>r.fulfill({json:[{asset_id:'fixture-local',name:'Local fixture',origin:'manual',starred:false,current:true,url:'/fixture.jpg'}]}));p.on('request',r=>{if(r.method()==='DELETE')deletes++;});await p.goto(process.env.FRAME_FLOW_URL||'http://127.0.0.1:6005');await p.locator('#username').fill(process.env.FRAME_FLOW_TEST_USERNAME);await p.locator('#password').fill(process.env.FRAME_FLOW_TEST_PASSWORD);await p.locator('#login-form button').click();await p.locator('.hero').waitFor();assert(await p.evaluate(()=>state.settings.mock));for(const lang of ['zh','en']){await p.evaluate(async lang=>{state.lang=lang;state.tab='local';await navigate('gallery')},lang);await p.locator('[data-delete="0"]').click();assert(await p.locator('#modal-content').textContent().then(x=>x.includes(lang==='zh'?'不会切换画框':'frame display is unchanged')));await p.locator('#modal-cancel').click();assert.equal(await p.locator('label[for="gallery-sort"]').textContent(),lang==='zh'?'排序方式':'Sort order');assert(await p.locator('#gallery-selection-help').textContent().then(x=>x.includes(lang==='zh'?'手动删除仍有效':'manual deletion still applies')));await p.evaluate(()=>navigate('playlists'));await p.locator('#new-playlist').click();assert.equal(await p.locator('label[for="playlist-mode"]').textContent(),lang==='zh'?'播放顺序':'Playback order');await p.locator('#modal-cancel').click();await p.evaluate(()=>navigate('dashboard'));await p.waitForFunction(()=>document.querySelector('#main').textContent.includes(t('weather')));assert(await p.locator('#main').textContent().then(x=>x.includes(lang==='zh'?'型号信息来源':'Model information source')));}assert.equal(deletes,0);console.log('Copy audit PASS: all literal translations present; bilingual sort/playback/model labels, local deletion and star scope verified; no deletions');}finally{await b.close()}})().catch(e=>{console.error(e);process.exit(1)});

scripts/ui-dashboard-preview.cjs

@@ -0,0 +1,6 @@
+/* Isolated Mock only: dashboard and gallery share the same read-only image viewer. */
+const assert=require('assert'),{chromium}=require('playwright');
+(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});let checks=0;
+try{for(const width of [1440,768,390]){const p=await browser.newPage({viewport:{width,height:1000}}),errors=[];p.on('pageerror',e=>errors.push(e.message));await p.route('**/api/v1/devices/*/current-content',r=>r.fulfill({json:{image_id:42,preview_url:'/fixture-preview.svg?thumbnail=true',synced:true,source_known:false,overrides:[]}}));await p.route('**/fixture-preview.svg*',r=>{return r.fulfill({contentType:'image/svg+xml',body:'<svg xmlns="http://www.w3.org/2000/svg" width="WIDTH" height="900"><rect width="1200" height="900" fill="#6c9c83"/><circle cx="600" cy="450" r="220" fill="#e9d9af"/></svg>'.replace('WIDTH',new URL(r.request().url()).searchParams.has('thumbnail')?'300':'1200')});});await p.route('**/api/v1/devices/*/images',r=>r.fulfill({json:[{image_id:42,name:'Fixture gallery',current:true,url:'/fixture-preview.svg'}]}));
+await p.goto(process.env.FRAME_FLOW_URL||'http://127.0.0.1:6005');await p.locator('#username').fill(process.env.FRAME_FLOW_TEST_USERNAME);await p.locator('#password').fill(process.env.FRAME_FLOW_TEST_PASSWORD);await p.locator('#login-form button').click();await p.locator('#current-frame-preview').waitFor();assert(await p.evaluate(()=>state.settings.mock));
+for(const lang of ['zh','en'])for(const theme of ['dark','light']){await p.evaluate(async({lang,theme})=>{state.lang=lang;document.documentElement.dataset.theme=theme;await navigate('dashboard')},{lang,theme});await p.waitForFunction(()=>document.querySelector('#current-frame-image')?.naturalWidth===1200);assert(await p.locator('#current-frame-preview').evaluate(e=>e.getBoundingClientRect().height)>=(width<=720?320:400));assert(await p.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));await p.locator('#current-frame-preview').focus();const fullImage=p.waitForRequest(r=>new URL(r.url()).pathname==='/fixture-preview.svg'&&!new URL(r.url()).searchParams.has('thumbnail'));await p.keyboard.press('Enter');await fullImage;await p.locator('dialog.image-viewer[open]').waitFor();await p.waitForFunction(()=>document.querySelector('#original-image')?.naturalWidth===1200);assert.equal(await p.locator('.image-viewer-name').textContent(),(lang==='zh'?'当前显示内容':'Currently displayed content')+' #42');assert.equal(await p.locator('.image-viewer-actions button').count(),3);const sizing=p.locator('.image-viewer-actions button[aria-pressed]');await sizing.nth(1).click();assert(await p.locator('.image-viewer-viewport').evaluate(e=>e.classList.contains('actual-size')));await sizing.nth(0).click();assert(!await p.locator('.image-viewer-viewport').evaluate(e=>e.classList.contains('actual-size')));await p.keyboard.press('Escape');assert(!await p.locator('#modal').evaluate(e=>e.open));await p.waitForFunction(()=>!document.body.classList.contains('image-viewer-open'));if(process.env.FRAME_FLOW_SCREENSHOT_DIR&&lang==='zh'&&theme==='dark'){require('fs').mkdirSync(process.env.FRAME_FLOW_SCREENSHOT_DIR,{recursive:true});await p.screenshot({path:process.env.FRAME_FLOW_SCREENSHOT_DIR+'/dashboard-'+width+'.png',fullPage:true});}await p.evaluate(()=>navigate('gallery'));await p.locator('[data-original="0"]').click();await p.locator('dialog.image-viewer[open]').waitFor();assert.equal(await p.locator('.image-viewer-actions button').count(),3);await p.locator('#modal-cancel').click();checks++;}assert.deepEqual(errors,[]);await p.close();}console.log('Dashboard preview: '+checks+' profiles PASS; larger preview, keyboard opening, shared gallery viewer, fit/actual size, Escape, no overflow');}finally{await browser.close()}})().catch(e=>{console.error(e);process.exit(1)});

scripts/ui-gallery-bootstrap.cjs

@@ -0,0 +1,10 @@
+/* Mock-only: slow device status and cloud metadata must not block real gallery controls. */
+const assert=require('assert'),fs=require('fs'),{chromium}=require('playwright');
+(async()=>{const base=process.env.FRAME_FLOW_URL;assert(base);const token=fs.readFileSync(process.env.FRAME_FLOW_ENV_FILE,'utf8').split('\n').find(x=>x.startsWith('FRAME_FLOW_TOKEN=')).slice(17);assert((await(await fetch(base+'/api/v1/settings',{headers:{Authorization:'Bearer '+token}})).json()).mock===true);const b=await chromium.launch({headless:true,executablePath:process.env.CHROME_EXECUTABLE||'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});
+ try{const p=await b.newPage({extraHTTPHeaders:{Authorization:'Bearer '+token}}),errors=[];p.on('pageerror',e=>errors.push(e.message));await p.route('**/api/v1/auth/me',r=>r.fulfill({json:{username:'fixture',csrf_token:''}}));let releaseStatus,releaseList;const pending=[];let checks=0;
+ await p.route('**/api/v1/devices',async r=>{pending.push('device');await new Promise(resolve=>releaseStatus=resolve);await r.fulfill({json:[{id:'living-room',name:'Fixture frame'}]});});
+ await p.route('**/api/v1/devices/*/images',async r=>{pending.push('list');await new Promise(resolve=>releaseList=resolve);await r.fulfill({json:[]});});
+ await p.goto(base+'/#gallery');await p.locator('#gallery-search').waitFor({timeout:5000});for(let i=0;i<100&&pending.length<2;i++)await p.waitForTimeout(20);assert.deepEqual(pending.sort(),['device','list']);assert(await p.locator('#gallery-upload').isEnabled());assert(await p.locator('#local-tab').isEnabled());assert.equal(await p.locator('.image-card,.placeholder-line,.image-pending,.page-loading').count(),0);checks++;if(process.env.FRAME_FLOW_SCREENSHOT_DIR){fs.mkdirSync(process.env.FRAME_FLOW_SCREENSHOT_DIR,{recursive:true});await p.screenshot({path:process.env.FRAME_FLOW_SCREENSHOT_DIR+'/gallery-list-pending.png'});}
+ await p.locator('#gallery-search').fill('kept query');await p.locator('#gallery-sort').selectOption('name');releaseStatus();releaseList();await p.waitForFunction(()=>document.querySelector('.gallery')?.getAttribute('aria-busy')==='false');assert.equal(await p.locator('#gallery-search').inputValue(),'kept query');assert.equal(await p.locator('#gallery-sort').inputValue(),'name');assert.equal(await p.locator('.card.empty').count(),1);checks++;
+ assert.deepEqual(errors,[]);console.log('Cold gallery bootstrap:',checks,'checks PASS; device/cloud requests blocked independently, real controls ready, input preserved');
+ }finally{await b.close();}})().catch(e=>{console.error(e.message);process.exit(1)});

scripts/ui-gallery-stars.cjs

@@ -8,8 +8,11 @@ const assert=require('assert'),{chromium}=require('playwright');
  try{
  await page.goto(process.env.FRAME_FLOW_URL||'http://127.0.0.1:6005');await page.locator('#username').fill(process.env.FRAME_FLOW_TEST_USERNAME);await page.locator('#password').fill(process.env.FRAME_FLOW_TEST_PASSWORD);await page.locator('#login-form button').click();await page.locator('.hero').waitFor();assert(await page.evaluate(()=>state.settings.mock));
  for(const lang of ['zh','en'])for(const width of [1440,390])for(const theme of ['dark','light']){
- await page.setViewportSize({width,height:1000});await page.evaluate(({lang,theme})=>{state.lang=lang;document.documentElement.dataset.theme=theme;shell();},{lang,theme});await page.locator('[data-page="gallery"]').click();await page.locator('#local-tab').click();await page.locator('[data-show="0"]').waitFor();const star=page.locator('.image-card').first().locator('button[aria-pressed]');assert(await star.count()===1);const original=await star.getAttribute('aria-pressed');await star.click();await page.waitForFunction(expected=>document.querySelector('.image-card button[aria-pressed]')?.getAttribute('aria-pressed')===expected,original==='true'?'false':'true');assert(await page.locator('[data-show="0"]').isDisabled());assert(await page.locator('[data-show="0"]').textContent()===(lang==='zh'?'当前图片':'Current image'));assert(await page.locator('[data-show="1"]').isEnabled());await page.locator('[data-show="0"]').evaluate(b=>b.onclick());assert(!await page.locator('#modal').evaluate(d=>d.open));assert(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));checks++;
+ await page.setViewportSize({width,height:1000});await page.evaluate(({lang,theme})=>{state.lang=lang;document.documentElement.dataset.theme=theme;shell();},{lang,theme});await page.locator('[data-page="gallery"]').click();await page.locator('#local-tab').click();await page.locator('[data-show="0"]').waitFor();const boxes=page.locator('.asset-select');const selected=()=>boxes.evaluateAll(xs=>xs.map(x=>x.checked));
+ assert.equal(await page.locator('#asset-invert').textContent(),lang==='zh'?'反选':'Invert selection');await boxes.nth(0).check();await page.locator('#asset-invert').click();assert.deepEqual(await selected(),[false,true]);await page.locator('#asset-invert').click();assert.deepEqual(await selected(),[true,false]);
+ await page.locator('#gallery-search').fill('Current fixture');await page.locator('#asset-invert').click();assert.deepEqual(await selected(),[false,false]);await page.locator('#asset-invert').click();assert.deepEqual(await selected(),[true,false]);await page.locator('#gallery-search').fill('no matching fixture');await page.locator('#asset-invert').click();assert.deepEqual(await selected(),[true,false]);await page.locator('#gallery-search').fill('');await page.locator('#asset-all').click();assert.deepEqual(await selected(),[true,true]);await page.locator('#asset-invert').click();assert.deepEqual(await selected(),[false,false]);
+ const star=page.locator('.image-card').first().locator('button[aria-pressed]');assert(await star.count()===1);const original=await star.getAttribute('aria-pressed');await star.click();await page.waitForFunction(expected=>document.querySelector('.image-card button[aria-pressed]')?.getAttribute('aria-pressed')===expected,original==='true'?'false':'true');assert(await page.locator('[data-show="0"]').isDisabled());assert(await page.locator('[data-show="0"]').textContent()===(lang==='zh'?'当前图片':'Current image'));assert(await page.locator('[data-show="1"]').isEnabled());await page.locator('[data-show="0"]').evaluate(b=>b.onclick());assert(!await page.locator('#modal').evaluate(d=>d.open));assert(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));checks++;
  }
- assert(writes===0);console.log('Current-image gallery button: '+checks+' profiles passed; disabled label, other image enabled, no display request');
+ assert(writes===0);console.log('Gallery inversion and current-image star: '+checks+' profiles passed; disabled label, other image enabled, no display request');
  }finally{await browser.close();}
 })().catch(e=>{console.error(e);process.exit(1)});

scripts/ui-history-localization.cjs

@@ -0,0 +1,17 @@
+const {chromium}=require('playwright');const fs=require('fs'),path=require('path'),assert=require('assert');
+const root=path.join(__dirname,'../pigway_frame_flow/web');
+(async()=>{const b=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});try{for(const width of [1440,768,390])for(const lang of ['zh','en']){
+ const p=await b.newPage({viewport:{width,height:900}});let errors=[];p.on('pageerror',e=>errors.push(e.message));let saved;
+ await p.addInitScript(lang=>localStorage.setItem('ff-language',lang),lang);
+ await p.route('**/*',async r=>{const u=new URL(r.request().url());if(u.pathname.startsWith('/api/')){
+ if(['PUT','POST'].includes(r.request().method())){saved=r.request().postDataJSON();return r.fulfill({json:{}})}
+ if(['/api/v1/jobs','/api/v1/assets','/api/v1/devices/living-room/images'].includes(u.pathname))return r.fulfill({json:[]});
+ if(u.pathname==='/api/v1/photo-sources')return r.fulfill({json:[]});
+ if(u.pathname==='/api/v1/integrations/synology-photos')return r.fulfill({json:{configured:true,connected:true}});
+ if(u.pathname.endsWith('/people'))return r.fulfill({json:[{id:1,name:'Test Person',count:5}]});
+ return r.fulfill({status:401,json:{error:{code:'UNAUTHORIZED',message:'Sign in required'}}});}
+ const f=u.pathname==='/'?'index.html':u.pathname.replace(/^\/ui\//,'');return r.fulfill({body:fs.readFileSync(path.join(root,f)),contentType:f.endsWith('.js')?'application/javascript':f.endsWith('.css')?'text/css':'text/html'});});
+ await p.goto('http://frame.test/');await p.locator('#login-form').waitFor();
+ await p.evaluate(async()=>{const previous=api;api=async()=>[{operation_id:'fixture',action:'display',device_id:'living-room',status:'FAILED',client_id:'scheduler',error:{code:'WRITE_DISABLED'},request_id:'fixture'}];state.devices=[{id:'living-room',name:'living-room'}];try{await views.history(state.epoch);}finally{api=previous;}});
+ const text=await p.locator('#main').innerText();assert(!text.includes('living-room'));assert(!text.includes('WRITE_DISABLED'));assert(text.includes(lang==='zh'?'客厅':'Living room'));assert(text.includes(lang==='zh'?'显示图片':'Display image'));assert(text.includes(lang==='zh'?'自动调度':'Scheduler'));assert.equal(errors.length,0);console.log('PASS history',width,lang);await p.close();
+ }}finally{await b.close()}})().catch(e=>{console.error(e);process.exit(1)});

scripts/ui-interval-schedule.cjs

@@ -0,0 +1,28 @@
+const {chromium}=require('playwright');const fs=require('fs'),path=require('path'),assert=require('assert');
+const root=path.join(__dirname,'../pigway_frame_flow/web');
+(async()=>{const b=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});try{for(const width of [1440,768,390])for(const lang of ['zh','en']){
+ const p=await b.newPage({viewport:{width,height:900}});let errors=[];p.on('pageerror',e=>errors.push(e.message));let saved;
+ await p.addInitScript(lang=>localStorage.setItem('ff-language',lang),lang);
+ await p.route('**/*',async r=>{const u=new URL(r.request().url());if(u.pathname.startsWith('/api/')){
+ if(['PUT','POST'].includes(r.request().method())){saved=r.request().postDataJSON();return r.fulfill({json:{}})}
+ if(['/api/v1/jobs','/api/v1/assets','/api/v1/devices/living-room/images'].includes(u.pathname))return r.fulfill({json:[]});
+ if(u.pathname==='/api/v1/photo-sources')return r.fulfill({json:[]});
+ if(u.pathname==='/api/v1/integrations/synology-photos')return r.fulfill({json:{configured:true,connected:true}});
+ if(u.pathname.endsWith('/people'))return r.fulfill({json:[{id:1,name:'Test Person',count:5}]});
+ return r.fulfill({status:401,json:{error:{code:'UNAUTHORIZED',message:'Sign in required'}}});}
+ const f=u.pathname==='/'?'index.html':u.pathname.replace(/^\/ui\//,'');return r.fulfill({body:fs.readFileSync(path.join(root,f)),contentType:f.endsWith('.js')?'application/javascript':f.endsWith('.css')?'text/css':'text/html'});});
+ await p.goto('http://frame.test/');await p.locator('#login-form').waitFor();
+ await p.evaluate(async()=>{state.templates=[{id:'daily-dashboard',name:'Dashboard',defaults:{}}];await jobEditor();});
+ for(const unit of ['hours','minutes']){
+ await p.locator('#job-schedule').selectOption(unit);await p.locator('#schedule-value').fill('2');
+ assert.equal(await p.locator('#schedule-value').getAttribute('type'),'number');
+ assert(await p.locator('#schedule-hint').innerText());
+ }
+ assert(!await p.evaluate(()=>document.documentElement.scrollWidth>innerWidth));
+ await p.locator('#job-name').fill('Test interval');
+ await p.locator('#job-form button[type=submit]').click();await p.waitForTimeout(100);
+ assert(saved);assert.deepEqual(saved.schedule,{type:'interval',interval_minutes:2});
+ await p.evaluate(async()=>{await jobEditor({id:'existing',name:'Existing',schedule:{type:'interval',interval_minutes:120},source:{type:'template',template:'daily-dashboard',data:{}},enabled:false,display_duration:0,restore_previous:false,priority:50});});
+ assert.equal(await p.locator('#job-schedule').inputValue(),'hours');assert.equal(await p.locator('#schedule-value').inputValue(),'2');
+ await p.evaluate(()=>{state.devices=[{id:'living-room',name:'我的相框'}];});assert.equal(await p.evaluate(()=>deviceDisplayName(state.devices[0])),'我的相框');assert.equal(await p.evaluate(()=>deviceDisplayName({id:'living-room',name:'living-room'})),lang==='zh'?'客厅':'Living room');await p.locator('#modal-cancel').click();await p.evaluate(async()=>{const previous=api;api=async()=>[{id:'fixture',name:'Family',device_id:'living-room',schedule:{type:'interval',interval_minutes:120},enabled:false}];try{await views.automation(state.epoch);}finally{api=previous;}});assert.equal(await p.locator('tbody td small').first().innerText(),'我的相框');assert.equal(errors.length,0,errors.join('\n'));console.log('PASS',width,lang);await p.close();
+ }}finally{await b.close()}})().catch(e=>{console.error(e);process.exit(1)});

scripts/ui-layout-audit.cjs

@@ -9,12 +9,12 @@ const assert=require('assert');const fs=require('fs');const {chromium}=require('
  await page.route('**/api/v1/integrations/synology-photos',async route=>{if(route.request().method()==='POST'){assert.deepStrictEqual(route.request().postDataJSON(),{username:'fixture-nas',password:'fixture-only'});connected=true;logins++;}await route.fulfill({json:{configured:true,connected}});});
  await page.route('**/api/v1/photo-sources',async route=>{assert(route.request().method()==='GET');await route.fulfill({json:[{id:'fixture-source',name:'NAS photos / NAS 照片',kind:'local',location:'.',enabled:false,people_filter:true,orientation:'auto'}]});});
  await page.goto(base);await page.locator('#username').fill(process.env.FRAME_FLOW_TEST_USERNAME);await page.locator('#password').fill(process.env.FRAME_FLOW_TEST_PASSWORD);await page.locator('#login-form button').click();await page.locator('.hero').waitFor();
- const viewports=process.env.FRAME_FLOW_VIEWPORTS?JSON.parse(process.env.FRAME_FLOW_VIEWPORTS):[1440,768,390].map(width=>({width,height:900}));
+ const viewports=process.env.FRAME_FLOW_VIEWPORTS?JSON.parse(process.env.FRAME_FLOW_VIEWPORTS):[1920,1440,768,390].map(width=>({width,height:900}));
  let checks=0;const failures=[];const out=process.env.FRAME_FLOW_SCREENSHOT_DIR;if(out)fs.mkdirSync(out,{recursive:true});
  async function inspect(label){
   const result=await page.evaluate(()=>{
-   const root=document.querySelector('dialog[open]')||document.querySelector('#main');const controls=[...root.querySelectorAll('button,select,input:not([type=checkbox]):not([type=radio]):not([type=file]),textarea')].filter(e=>e.checkVisibility({checkOpacity:true,checkVisibilityCSS:true})&&!e.closest('[hidden]')).map(e=>({id:e.id||e.textContent.trim().slice(0,24),r:e.getBoundingClientRect()}));const close=[];
-   for(let i=0;i<controls.length;i++)for(let j=i+1;j<controls.length;j++){const a=controls[i].r,b=controls[j].r;const x=Math.min(a.right,b.right)-Math.max(a.left,b.left),y=Math.min(a.bottom,b.bottom)-Math.max(a.top,b.top);const dx=Math.max(a.left,b.left)-Math.min(a.right,b.right),dy=Math.max(a.top,b.top)-Math.min(a.bottom,b.bottom);if((x>1&&dy<7.5)||(y>1&&dx<7.5))close.push([controls[i].id,controls[j].id]);}
+   const root=document.querySelector('dialog[open]')||document.querySelector('#main');const controls=[...root.querySelectorAll('button,select,input:not([type=checkbox]):not([type=radio]):not([type=file]),textarea')].filter(e=>e.checkVisibility({checkOpacity:true,checkVisibilityCSS:true})&&!e.closest('[hidden]')).map(e=>({id:e.id||e.textContent.trim().slice(0,24),compact:!!e.closest('.image-card .actions'),r:e.getBoundingClientRect()}));const close=[];
+   for(let i=0;i<controls.length;i++)for(let j=i+1;j<controls.length;j++){const a=controls[i].r,b=controls[j].r;const x=Math.min(a.right,b.right)-Math.max(a.left,b.left),y=Math.min(a.bottom,b.bottom)-Math.max(a.top,b.top);const dx=Math.max(a.left,b.left)-Math.min(a.right,b.right),dy=Math.max(a.top,b.top)-Math.min(a.bottom,b.bottom);const gap=controls[i].compact&&controls[j].compact?5.5:7.5;if((x>1&&dy<gap)||(y>1&&dx<gap))close.push([controls[i].id,controls[j].id]);}
    const dialog=document.querySelector('dialog[open]');const rect=dialog?.getBoundingClientRect();
    const clippedDialog=!!rect&&(rect.left<0||rect.right>innerWidth||rect.top<0||rect.bottom>innerHeight);
    const clippedNav=innerWidth<=720&&[...document.querySelectorAll('nav button')].some(button=>{const r=button.getBoundingClientRect();return button.scrollHeight>button.clientHeight||r.height<44;});
@@ -25,7 +25,7 @@ const assert=require('assert');const fs=require('fs');const {chromium}=require('
   await page.setViewportSize({width,height});await page.evaluate(({lang,theme})=>{state.lang=lang;document.documentElement.dataset.theme=theme;shell();},{lang,theme});
   for(const view of ['dashboard','gallery','photo-sources','upload','templates','automation','playlists','history','settings','studio','connections']){await page.evaluate(view=>navigate(view),view);await inspect(`${view}/${width}/${lang}/${theme}`);}
   await page.evaluate(()=>navigate('studio'));await page.locator('.manual-collage summary').click();await inspect(`Manual collage/${width}/${lang}/${theme}`);await page.evaluate(()=>navigate('photo-sources'));await page.locator('#photos-login').click();await inspect(`Photos login/${width}/${lang}/${theme}`);await page.locator('#modal-cancel').click();
-  await page.locator('#add-photo-source').click();assert(await page.locator('#source-credential').isHidden());assert(await page.locator('#source-oauth').isHidden());await inspect(`NAS source/${width}/${lang}/${theme}`);await page.locator('#source-kind').selectOption('google-drive');assert(await page.locator('#source-oauth').isVisible());assert(await page.locator('#source-local-quality').isHidden());await inspect(`Drive source/${width}/${lang}/${theme}`);await page.locator('#modal-cancel').click();
+  await page.locator('#add-photo-source').click();assert(await page.locator('#source-credential').isHidden());assert(await page.locator('#source-oauth').isHidden());await inspect(`NAS source/${width}/${lang}/${theme}`);await page.locator('#modal-cancel').click();
   await page.evaluate(()=>navigate('automation'));await page.locator('#new-job').click();await inspect(`Job/${width}/${lang}/${theme}`);await page.locator('#modal-cancel').click();
   await page.evaluate(()=>navigate('playlists'));await page.locator('#new-playlist').click();await inspect(`Playlist/${width}/${lang}/${theme}`);await page.locator('#modal-cancel').click();
   await page.evaluate(()=>displayDialog({type:'image',image_id:1}));await inspect(`Display options/${width}/${lang}/${theme}`);await page.locator('#modal-cancel').click();
@@ -33,6 +33,6 @@ const assert=require('assert');const fs=require('fs');const {chromium}=require('
   if(out&&lang==='zh'&&theme==='dark'){await page.evaluate(()=>navigate('photo-sources'));await page.screenshot({path:out+`/photos-${width}.png`,fullPage:true});}
  }
  await page.evaluate(()=>navigate('photo-sources'));await page.locator('#photos-login').click();await page.locator('#photos-login-user').fill('fixture-nas');await page.locator('#photos-login-password').fill('fixture-only');await page.locator('#photos-login-form button[type=submit]').click();await page.locator('#photos-login').filter({hasText:'Sign in again'}).waitFor();assert(logins===1);checks++;
- assert.deepStrictEqual(errors,[]);assert.deepStrictEqual(failures,[],JSON.stringify(failures));console.log('Layout audit:',checks,'passed; 11 pages plus local gallery, 6 modal states, '+(viewports.length*4)+' viewport/language/theme combinations; console errors:',errors.length);
+ assert.deepStrictEqual(errors,[]);assert.deepStrictEqual(failures,[],JSON.stringify(failures));console.log('Layout audit:',checks,'passed; 11 pages plus local gallery, 5 modal states, '+(viewports.length*4)+' viewport/language/theme combinations; console errors:',errors.length);
  }finally{await browser.close();}
 })().catch(e=>{console.error(e.message);process.exit(1)});

scripts/ui-login-layout.cjs

@@ -0,0 +1,17 @@
+const {chromium}=require('playwright');const fs=require('fs');const path=require('path');const assert=require('assert');
+const root=path.resolve(__dirname,'../pigway_frame_flow/web');const out=process.env.FRAME_FLOW_SCREENSHOT_DIR;if(out)fs.mkdirSync(out,{recursive:true});
+(async()=>{const b=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});let count=0;
+try{for(const width of [1440,768,390,320])for(const lang of ['zh','en'])for(const theme of ['dark','light']){
+const p=await b.newPage({viewport:{width,height:900}});const errors=[];p.on('pageerror',e=>errors.push(e.message));
+await p.addInitScript(({lang,theme})=>{localStorage.setItem('ff-language',lang);localStorage.setItem('ff-theme',theme)},{lang,theme});
+await p.route('**/*',async r=>{const u=new URL(r.request().url());if(u.pathname.startsWith('/api/')){if(u.pathname==='/api/v1/version')return r.fulfill({json:{version:'0.1.9',commit:'ba9424a-ui',build_time:'validation'}});return r.fulfill({status:401,json:{error:{code:'UNAUTHORIZED',message:'Sign in required'}}});}let f=u.pathname==='/'?'index.html':u.pathname.replace(/^\/ui\//,'');const file=path.join(root,f);if(!file.startsWith(root)||!fs.existsSync(file))return r.fulfill({status:404,body:''});return r.fulfill({body:fs.readFileSync(file),contentType:f.endsWith('.css')?'text/css':f.endsWith('.js')?'application/javascript':'text/html'});});
+await p.goto('http://frame.test/');await p.locator('#login-form').waitFor();await p.waitForTimeout(60);
+assert.equal(await p.locator('#device option:checked').innerText(),lang==='zh'?'客厅':'Living room');
+const layout=await p.evaluate(()=>{const q=s=>document.querySelector(s).getBoundingClientRect();return {overflow:document.documentElement.scrollWidth>innerWidth,card:q('.login-card').toJSON(),form:q('#login-form').toJSON(),user:q('#username').toJSON(),password:q('#password').toJSON(),remember:document.querySelector('#remember-login').closest('label').getBoundingClientRect().toJSON(),button:q('#login-form button').toJSON(),label:document.querySelector('#remember-login').labels[0].innerText}});
+assert(!layout.overflow,JSON.stringify({width,lang,theme,layout}));assert(layout.password.top-layout.user.bottom>=24);assert(layout.button.top-layout.remember.bottom>=20);assert(layout.button.width>=layout.form.width-1);assert.equal(errors.length,0,errors.join('\n'));
+// Language switching and custom names must not change the internal device ID.
+await p.evaluate(()=>{state.devices=[{id:'living-room',name:'我的画框'}];shell()});assert.equal(await p.locator('#device option:checked').innerText(),'我的画框');
+await p.evaluate(()=>{state.devices=[];shell();login()});
+if(out&&lang==='zh'&&theme==='dark'&&[1440,390].includes(width))await p.screenshot({path:path.join(out,`login-${width}.png`),fullPage:true});
+console.log('PASS',width,lang,theme);count++;await p.close();}
+console.log('TOTAL',count,'profiles');}finally{await b.close()}})().catch(e=>{console.error(e);process.exit(1)});

scripts/ui-photos-api-form.cjs

@@ -0,0 +1,23 @@
+const {chromium}=require('playwright');const fs=require('fs'),path=require('path'),assert=require('assert');
+const root=path.join(__dirname,'../pigway_frame_flow/web');
+(async()=>{const b=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});try{for(const width of [1440,768,390])for(const lang of ['zh','en']){
+ const p=await b.newPage({viewport:{width,height:900}});let errors=[];p.on('pageerror',e=>errors.push(e.message));let saved;
+ await p.addInitScript(lang=>localStorage.setItem('ff-language',lang),lang);
+ await p.route('**/*',async r=>{const u=new URL(r.request().url());if(u.pathname.startsWith('/api/')){
+ if(r.request().method()==='PUT'){saved=r.request().postDataJSON();return r.fulfill({json:{}})}
+ if(u.pathname==='/api/v1/photo-sources')return r.fulfill({json:[]});
+ if(u.pathname==='/api/v1/integrations/synology-photos')return r.fulfill({json:{configured:true,connected:true}});
+ if(u.pathname.endsWith('/people'))return r.fulfill({json:[{id:1,name:'Test Person',count:5}]});
+ return r.fulfill({status:401,json:{error:{code:'UNAUTHORIZED',message:'Sign in required'}}});}
+ const f=u.pathname==='/'?'index.html':u.pathname.replace(/^\/ui\//,'');return r.fulfill({body:fs.readFileSync(path.join(root,f)),contentType:f.endsWith('.js')?'application/javascript':f.endsWith('.css')?'text/css':'text/html'});});
+ await p.goto('http://frame.test/');await p.locator('#login-form').waitFor();await p.evaluate(()=>photoSourceForm());
+ assert(!(await p.locator('#source-kind').isVisible()));assert(!(await p.locator('#source-id').isVisible()));assert(!(await p.locator('#source-synology-previews').isVisible()));
+ assert.equal(await p.locator('#source-kind').inputValue(),'synology-photos');assert.match(await p.locator('#source-id').inputValue(),/^photos-[a-z0-9-]+$/);
+ const text=await p.locator('#modal').innerText();assert(!/\/photos|本地目录|local.folder|mounted/i.test(text));
+ assert(await p.locator('#source-people-space').isVisible());await p.locator('#source-people-load').click();await p.locator('[data-person-id], #source-people-panel input[type=checkbox]').last().waitFor();
+ assert(!await p.evaluate(()=>document.documentElement.scrollWidth>innerWidth));
+ await p.locator('#source-name').fill('Family');
+ await p.locator('#photo-source-form button[type=submit]').click();await p.waitForTimeout(100);
+ assert(saved);assert.equal(saved.kind,'synology-photos');assert.equal(saved.synology_previews,false);
+ await p.evaluate(()=>photoSourceForm({id:'family-photos',name:'Family',kind:'synology-photos',location:'.',people_filter:true,person_ids:[1],people_space:'personal',person_match:'all'}));assert.equal(await p.locator('#source-id').inputValue(),'family-photos');assert.equal(await p.locator('#source-people-space').inputValue(),'personal');assert.equal(await p.locator('#source-person-match').inputValue(),'all');assert(await p.locator('#source-people-filter').isChecked());if(lang==='zh')await p.screenshot({path:'/tmp/frame-source-'+width+'.png',fullPage:true});assert.equal(errors.length,0,errors.join('\n'));console.log('PASS',width,lang);await p.close();
+ }}finally{await b.close()}})().catch(e=>{console.error(e);process.exit(1)});

scripts/ui-photos-api.cjs

@@ -0,0 +1,4 @@
+/* Isolated Mock UI only: explicit API type, people spaces, payload and no mount wording. */
+const assert=require('assert'),{chromium}=require('playwright');
+(async()=>{const b=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});let checks=0;
+try{for(const width of [1440,390])for(const lang of ['zh','en'])for(const theme of ['light','dark']){const p=await b.newPage({viewport:{width,height:1000}}),errors=[];let saved;const spaces=[];p.on('pageerror',e=>errors.push(e.message));await p.route('**/api/v1/photo-sources',r=>r.fulfill({json:[]}));await p.route('**/api/v1/photo-sources/api-fixture',r=>{saved=r.request().postDataJSON();return r.fulfill({json:{...saved,id:'api-fixture'}})});await p.route('**/api/v1/integrations/synology-photos',r=>r.fulfill({json:{configured:true,connected:true}}));await p.route('**/api/v1/integrations/synology-photos/people?*',r=>{spaces.push(new URL(r.request().url()).searchParams.get('space'));return r.fulfill({json:[{id:7,name:'Fixture person',count:3,named:true}]})});await p.goto(process.env.FRAME_FLOW_URL||'http://127.0.0.1:6005');await p.locator('#username').fill(process.env.FRAME_FLOW_TEST_USERNAME);await p.locator('#password').fill(process.env.FRAME_FLOW_TEST_PASSWORD);await p.locator('#login-form button').click();await p.locator('.hero').waitFor();assert(await p.evaluate(()=>state.settings.mock));await p.evaluate(async({lang,theme})=>{state.lang=lang;document.documentElement.dataset.theme=theme;await navigate('photo-sources')},{lang,theme});await p.locator('#add-photo-source').click();await p.locator('#source-kind').selectOption('synology-photos');await p.locator('#source-id').fill('api-fixture');await p.locator('#source-name').fill('Photos API');assert(await p.locator('#source-credential').isHidden());assert(await p.locator('#source-oauth').isHidden());assert(await p.locator('#source-synology-previews').isHidden());assert(await p.locator('#source-orientation').isEnabled());await p.locator('#source-people-filter').check();await p.locator('#source-people-load').click();await p.locator('[data-person="7"]').check();await p.locator('#source-people-space').selectOption('personal');await p.locator('#source-people-load').click();assert(!await p.locator('[data-person="7"]').isChecked());await p.locator('[data-person="7"]').check();await p.locator('#source-person-match').selectOption('all');assert(await p.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));if(process.env.FRAME_FLOW_SCREENSHOT_DIR&&lang==='zh'&&theme==='dark'){require('fs').mkdirSync(process.env.FRAME_FLOW_SCREENSHOT_DIR,{recursive:true});await p.screenshot({path:process.env.FRAME_FLOW_SCREENSHOT_DIR+'/photos-api-'+width+'.png'});}await p.locator('#photo-source-form button[type="submit"]').click();await p.waitForFunction(()=>!document.querySelector('#modal').open);assert.equal(saved.kind,'synology-photos');assert.equal(saved.people_space,'personal');assert.equal(saved.person_match,'all');assert.deepEqual(saved.person_ids,[7]);assert.equal(saved.credential_env,null);assert.equal(saved.synology_previews,false);assert.deepEqual(spaces,['shared','personal']);assert.deepEqual(errors,[]);await p.close();checks++;}console.log('Photos API UI:',checks,'profiles PASS; type/space/person any-all/config and responsive layout verified');}finally{await b.close()}})().catch(e=>{console.error(e);process.exit(1)});

scripts/ui-progressive-loading.cjs

@@ -18,8 +18,9 @@ const assert=require('assert'),fs=require('fs'),{chromium}=require('playwright')
    const metadata=new Promise(resolve=>metadataRequested=resolve);const image=new Promise(resolve=>imageRequested=resolve);
    await page.evaluate(()=>{window.navigation=navigate('gallery');});await metadata;
    assert.equal(await page.locator('.image-pending,.placeholder-line,.page-placeholder').count(),0);assert.equal(await page.locator('.image-card').count(),0);assert.equal(await page.locator('.page-loading').count(),0);checks++;
+   assert(await page.locator('#cloud-tab').isVisible());assert(await page.locator('#local-tab').isEnabled());assert(await page.locator('#gallery-upload').isEnabled());assert(await page.locator('#gallery-search').isVisible());assert(await page.locator('#gallery-sort').isEnabled());assert(await page.locator('#gallery-list-status').isVisible());assert.equal(await page.locator('.card.empty').count(),0);await page.locator('#gallery-search').fill('Progressive');await page.locator('#gallery-sort').selectOption('name');checks++;
    releaseMetadata();await image;await page.evaluate(()=>window.navigation);
-   assert(await page.locator('#gallery-upload').isEnabled());assert.equal(await page.locator('.image-loading .spinner').count(),1);assert.equal(await page.locator('.image-pending').count(),0);checks++;
+   assert.equal(await page.locator('#gallery-search').inputValue(),'Progressive');assert.equal(await page.locator('#gallery-sort').inputValue(),'name');assert(await page.locator('#gallery-upload').isEnabled());assert.equal(await page.locator('.image-loading .spinner').count(),1);assert.equal(await page.locator('.image-pending').count(),0);checks++;
    assert(await page.locator('.image-loading').evaluate(box=>{const a=box.getBoundingClientRect(),b=box.querySelector('.spinner').getBoundingClientRect();return Math.abs(a.x+a.width/2-b.x-b.width/2)<1&&Math.abs(a.y+a.height/2-b.y-b.height/2)<1;}));checks++;
    releaseImage();await page.waitForFunction(()=>document.querySelector('.thumb')?.naturalWidth===300&&!document.querySelector('.image-loading'));checks++;
    await page.evaluate(()=>navigate('upload'));
@@ -34,6 +35,15 @@ const assert=require('assert'),fs=require('fs'),{chromium}=require('playwright')
    assert.equal(await page.locator('.image-pending,.placeholder-line,.page-placeholder').count(),0);assert.equal(await page.locator('.page-loading').count(),0);checks++;
    releaseDevice();await page.evaluate(()=>window.navigation);await page.unroute('**/api/v1/devices/living-room');
   }
+  await page.evaluate(()=>{state.galleryCache?.clear();state.tab='cloud';});
+  let releaseSlow,slowRequested;const slow=new Promise(resolve=>slowRequested=resolve);
+  await page.route('**/api/v1/devices/*/images',async r=>{slowRequested();await new Promise(resolve=>releaseSlow=resolve);await r.fulfill({json:[]});});
+  await page.evaluate(()=>{window.slowNavigation=navigate('gallery');});await slow;await page.locator('#local-tab').click();await page.waitForFunction(()=>state.tab==='local'&&document.querySelector('#local-tab')?.classList.contains('active'));releaseSlow();await page.evaluate(()=>window.slowNavigation);assert.equal(await page.evaluate(()=>state.tab),'local');assert(await page.locator('#gallery-search').isVisible());checks++;
+  await page.unroute('**/api/v1/devices/*/images');
+  await page.evaluate(()=>{state.galleryCache?.clear();state.tab='cloud';});
+  await page.route('**/api/v1/devices/*/images',r=>r.fulfill({status:503,json:{error:{code:'CLOUD_UNAVAILABLE',message:'fixture unavailable'}}}));
+  await page.evaluate(()=>navigate('gallery'));assert(await page.locator('#gallery-search').isVisible());assert(await page.locator('#local-tab').isEnabled());assert.equal(await page.locator('#gallery-list-status').getAttribute('role'),'alert');checks++;
+  await page.unroute('**/api/v1/devices/*/images');
   let releaseJobs,jobsRequested;await page.route('**/api/v1/jobs',async r=>{jobsRequested();await new Promise(resolve=>releaseJobs=resolve);await r.fulfill({json:[]});});
   await page.route('**/api/v1/assets?*',r=>r.fulfill({json:[{asset_id:'local-fixture',name:'Local fixture',url:'/local-fixture.svg',origin:'manual',starred:false}]}));
   await page.route('**/local-fixture.svg',r=>r.fulfill({contentType:'image/svg+xml',body:'<svg xmlns="http://www.w3.org/2000/svg" width="300" height="400"/>'}));

scripts/verify-photos-api-container.py

@@ -0,0 +1,45 @@
+"""Smoke-check an already running isolated Mock container, via its loopback HTTP."""
+
+import json
+import os
+import time
+import urllib.request
+from pathlib import Path
+
+
+def main():
+    assert os.getuid() == 10333 and os.getgid() == 10333
+    assert not Path("/photos").exists()
+    for _ in range(30):
+        try:
+            with urllib.request.urlopen(
+                "http://127.0.0.1:18787/ready", timeout=2
+            ) as response:
+                assert json.load(response)["status"] == "ready"
+            break
+        except OSError:
+            time.sleep(1)
+    else:
+        raise SystemExit("Mock readiness failed")
+    with urllib.request.urlopen(
+        "http://127.0.0.1:18787/api/v1/version", timeout=2
+    ) as response:
+        version = json.load(response)
+    assert version["version"] == "0.1.9"
+    assert Path("/data/frameflow.db").is_file()
+    print(
+        json.dumps(
+            {
+                "ready": True,
+                "version": version["version"],
+                "commit": version["commit"],
+                "uid": os.getuid(),
+                "gid": os.getgid(),
+                "no_photos_mount": True,
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

scripts/verify-photos-api.py

@@ -0,0 +1,112 @@
+"""Read-only live Photos check. Never creates an app, worker, job or frame driver."""
+
+import argparse
+import io
+import json
+import os
+from pathlib import Path
+
+from PIL import Image
+
+from pigway_frame_flow.errors import FlowError
+from pigway_frame_flow.providers.photo_sources import PhotoSourceInput, PhotoSources
+from pigway_frame_flow.settings import Settings
+from pigway_frame_flow.storage.database import Database
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--bootstrap", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    if Path("/photos").exists():
+        raise SystemExit("Verification requires /photos to be absent")
+    bootstrap = json.loads(args.bootstrap.read_text())
+    os.environ["SYNOLOGY_PHOTOS_URL"] = bootstrap["url"]
+    os.environ["SYNOLOGY_PHOTOS_CERT_SHA256"] = bootstrap["pin"]
+    settings = Settings(mock=True, write_enabled=False, api_key="", api_token="")
+    settings.data_dir.mkdir(parents=True, exist_ok=True)
+    settings.config_dir.mkdir(parents=True, exist_ok=True)
+    session = settings.config_dir / "synology-photos-session.json"
+    session.write_text(json.dumps(bootstrap["session"]))
+    session.chmod(0o600)
+    db = Database(settings.data_dir / "verification.db")
+    photos = PhotoSources(db, settings, None)
+    report = {"no_photos_mount": True, "device_writes": 0, "spaces": {}}
+    try:
+        for space in ("shared", "personal"):
+            people = photos.synology.people(space)
+            candidates = sorted(
+                (p for p in people if p["count"] > 1), key=lambda p: p["count"]
+            )
+            if len(candidates) < 2:
+                raise RuntimeError("Need two accessible populated person albums")
+            selected = [p["id"] for p in candidates[:2]]
+            one = photos.synology.items(selected[:1], space=space)
+            two = photos.synology.items(selected[1:], space=space)
+            ids_one, ids_two = {r["id"] for r in one}, {r["id"] for r in two}
+            any_rows = photos.synology.items(selected, "any", space=space)
+            all_rows = photos.synology.items(selected, "all", space=space)
+            assert {r["id"] for r in any_rows} == ids_one | ids_two
+            assert {r["id"] for r in all_rows} == ids_one & ids_two
+            source_id = "live-" + space
+            photos.save(
+                source_id,
+                PhotoSourceInput(
+                    name="Read-only verification",
+                    kind="synology-photos",
+                    location=".",
+                    people_space=space,
+                    people_filter=True,
+                    person_ids=selected,
+                ),
+            )
+            catalog = photos.catalog(source_id)
+            assert catalog
+            data, _, _ = photos.read(source_id, catalog[0]["id"])
+            with Image.open(io.BytesIO(data)) as image:
+                image.load()
+                decoded = {
+                    "width": image.width,
+                    "height": image.height,
+                    "format": image.format,
+                }
+            cache = photos.synology.image_cache
+            before = cache.downloads
+            assert photos.read(source_id, catalog[0]["id"])[0] == data
+            assert cache.downloads == before
+            report["spaces"][space] = {
+                "people": len(people),
+                "any_count": len(any_rows),
+                "all_count": len(all_rows),
+                "catalog_count": len(catalog),
+                "bytes": len(data),
+                "decoded": decoded,
+                "cache_reused": True,
+            }
+        # A deliberately invalid session is isolated to this verification config;
+        # no logout request or change is made to the original NAS session.
+        photos.synology.path.write_text(
+            json.dumps({"sid": "frameflow-deliberately-invalid-session"})
+        )
+        try:
+            photos.synology.people()
+        except FlowError as error:
+            assert error.status == 409
+            report["expired_session"] = "explicit_reconnect_required"
+        else:
+            raise RuntimeError("Invalid session unexpectedly accepted")
+        report["cache_bytes"] = sum(
+            p.stat().st_size
+            for p in (settings.data_dir / "cache/synology-photos").glob("*.image")
+        )
+        assert report["cache_bytes"] <= settings.photos_cache_bytes
+        report["original_download"] = "not_supported_by_this_verified_implementation"
+        args.output.write_text(json.dumps(report, indent=2) + "\n")
+        print(json.dumps(report, indent=2))
+    finally:
+        session.unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    main()

tests/conftest.py

@@ -30,3 +30,17 @@ def client(app):
 @pytest.fixture
 def service(app):
     return app.state.service
+
+
+@pytest.fixture
+def legacy_photo_engine(monkeypatch):
+    """Exercise retained legacy internals without weakening production policy.
+
+    These fixtures cover rendering, retention and migration algorithms that used
+    filesystem inputs historically. API boundary tests never use this override.
+    """
+    from pigway_frame_flow.providers.photo_sources import PhotoSources
+
+    monkeypatch.setattr(
+        PhotoSources, "require_api_source", staticmethod(lambda source: None)
+    )

tests/schema-contract.json

@@ -869,6 +869,7 @@
         "type": "string",
         "enum": [
           "local",
+          "synology-photos",
           "webdav",
           "google-drive",
           "alipan",
@@ -882,6 +883,19 @@
         "minLength": 1,
         "title": "Location"
       },
+      "nas_root_path": {
+        "anyOf": [
+          {
+            "type": "string",
+            "maxLength": 2048,
+            "pattern": "^/"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "title": "Nas Root Path"
+      },
       "recursive": {
         "type": "boolean",
         "title": "Recursive",
@@ -930,6 +944,20 @@
         ],
         "title": "Orientation"
       },
+      "minimum_short_edge": {
+        "type": "integer",
+        "maximum": 50000.0,
+        "minimum": 0.0,
+        "title": "Minimum Short Edge",
+        "default": 0
+      },
+      "minimum_long_edge": {
+        "type": "integer",
+        "maximum": 50000.0,
+        "minimum": 0.0,
+        "title": "Minimum Long Edge",
+        "default": 0
+      },
       "minimum_sharpness": {
         "type": "number",
         "maximum": 10000.0,
@@ -1021,6 +1049,7 @@
         "type": "string",
         "enum": [
           "local",
+          "synology-photos",
           "webdav",
           "google-drive",
           "alipan",
@@ -1034,6 +1063,19 @@
         "minLength": 1,
         "title": "Location"
       },
+      "nas_root_path": {
+        "anyOf": [
+          {
+            "type": "string",
+            "maxLength": 2048,
+            "pattern": "^/"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "title": "Nas Root Path"
+      },
       "recursive": {
         "type": "boolean",
         "title": "Recursive",
@@ -1082,6 +1124,20 @@
         ],
         "title": "Orientation"
       },
+      "minimum_short_edge": {
+        "type": "integer",
+        "maximum": 50000.0,
+        "minimum": 0.0,
+        "title": "Minimum Short Edge",
+        "default": 0
+      },
+      "minimum_long_edge": {
+        "type": "integer",
+        "maximum": 50000.0,
+        "minimum": 0.0,
+        "title": "Minimum Long Edge",
+        "default": 0
+      },
       "minimum_sharpness": {
         "type": "number",
         "maximum": 10000.0,
@@ -1190,6 +1246,17 @@
         ],
         "title": "Caption"
       },
+      "source_path": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "title": "Source Path"
+      },
       "provider_preview": {
         "type": "boolean",
         "title": "Provider Preview",

tests/test_api.py

@@ -338,7 +338,8 @@ def test_unknown_same_idempotency_key_returns_original(client, service):
     fresh = client.post(
         "/api/v1/display", json=payload, headers={"Idempotency-Key": "new-key"}
     )
-    assert fresh.status_code == 409
+    assert fresh.status_code == 202
+    assert fresh.json()["operation_id"] != original.json()["operation_id"]
 
 
 def test_schema_contract(client):
@@ -442,3 +443,16 @@ def test_storage_display_name_environment(monkeypatch):
     assert Settings().storage_name == "Family NAS"
     monkeypatch.setenv("FRAME_FLOW_STORAGE_NAME", "  ")
     assert Settings().storage_name == "NAS"
+
+
+def test_settings_device_catalog_does_not_fetch_cloud_status(
+    client, service, monkeypatch
+):
+    registry = service.registry
+    for driver in registry.drivers.values():
+        monkeypatch.setattr(
+            driver, "device", lambda *a, **kw: pytest.fail("Cloud status fetched")
+        )
+    result = client.get("/api/v1/settings")
+    assert result.status_code == 200
+    assert {d["id"] for d in result.json()["device_catalog"]} == set(registry.drivers)

tests/test_client.py

@@ -165,6 +165,23 @@ def test_transport_failure_records_safe_category_without_replay(exception, categ
     assert s.request.call_count == (3 if category == "connect_timeout" else 1)
 
 
+def test_connection_establishment_failure_is_unsent_and_bounded(transport_clock):
+    from urllib3.exceptions import MaxRetryError, NewConnectionError
+
+    s = session()
+    s.request.side_effect = requests.ConnectionError(
+        MaxRetryError(None, "/private", NewConnectionError(None, "private"))
+    )
+    c = KokonnaClient("secret", True, s)
+    with pytest.raises(FlowError) as error:
+        c.display(1)
+    assert error.value.code == "CLOUD_UNAVAILABLE"
+    assert error.value.details["write_outcome"] == "not_sent"
+    assert error.value.details["transport_error"] == "connect_error"
+    assert s.request.call_count == 3
+    assert "private" not in str(error.value.details)
+
+
 @pytest.mark.parametrize("write", [False, True])
 def test_connect_timeout_retries_then_succeeds(write, transport_clock):
     s = session({"success": True})

tests/test_display.py

@@ -71,22 +71,24 @@ def test_nested_overrides(service):
     assert service.registry.get("living-room").get_current_image() == 1
 
 
-def test_no_retry_unknown(service):
+def test_unknown_does_not_block_new_independent_upload(service):
     driver = service.registry.get("living-room")
+    attempts = []
 
-    def timeout(*a):
+    def timeout(*args):
+        attempts.append(args)
         raise FlowError(ErrorCode.WRITE_RESULT_UNKNOWN, "Write outcome unknown", 502)
 
     driver.upload = timeout
-    id = submit(service)
+    first = submit(service)
     service.process_one()
-    assert service.operation(id)["status"] == "UNKNOWN"
-    with pytest.raises(FlowError):
-        submit(service)
-    assert service.process_one() is False
-    assert service.reconcile(id)["resolved"] is False
-    assert service.reconcile(id, True)["resolved"] is True
-    assert service.operation(id)["status"] == "FAILED"
+    assert service.operation(first)["status"] == "UNKNOWN"
+    second = submit(service, priority=10)
+    assert second != first
+    assert service.process_one()
+    assert service.operation(first)["status"] == "FAILED"
+    assert service.operation(second)["status"] == "UNKNOWN"
+    assert len(attempts) == 2
 
 
 def test_restart_preserves_override(service):
@@ -145,6 +147,105 @@ def test_delete_restore_reference_protected(service):
     service.process_one()
     assert service.operation(delete)["status"] == "FAILED"
     assert service.operation(delete)["error"]["code"] == "CONFLICT"
+    assert (
+        service.operation(delete)["error"]["details"]["reason"]
+        == "RESTORE_IMAGE_PROTECTED"
+    )
+
+
+@pytest.mark.parametrize("automatic", [True, False])
+def test_completed_restore_consumes_self_reference(client, service, automatic):
+    display = submit(service, 60, True)
+    service.process_one()
+    service.sync()
+    if automatic:
+        expired(service, display)
+        service.expire()
+    else:
+        service.submit("restore", {}, "living-room", "admin", "restore-test")
+        service.process_one()
+    service.sync()
+    assert service.state("living-room")["previous_image_id"] is None
+    assert not client.get("/api/v1/devices/living-room").json()["can_restore"]
+    delete = service.submit(
+        "delete",
+        {"image_id": 1, "confirm_current": True},
+        "living-room",
+        "admin",
+        "delete-restored",
+    )
+    service.process_one()
+    assert service.operation(delete)["status"] == "COMPLETED"
+
+
+@pytest.mark.parametrize("via_delete", [False, True])
+def test_existing_self_reference_is_repaired(client, service, via_delete):
+    service.state("living-room")
+    service.db.execute(
+        "UPDATE device_state SET previous_image_id=1,managed_image_id=1 WHERE device_id=?",
+        ("living-room",),
+    )
+    if via_delete:
+        operation = service.submit(
+            "delete",
+            {"image_id": 1, "confirm_current": True},
+            "living-room",
+            "admin",
+            "delete-stale-reference",
+        )
+        service.process_one()
+        assert service.operation(operation)["status"] == "COMPLETED"
+    else:
+        assert not client.get("/api/v1/devices/living-room?refresh=true").json()[
+            "can_restore"
+        ]
+    assert service.state("living-room")["previous_image_id"] is None
+
+
+@pytest.mark.parametrize(
+    "protection",
+    ["override", "base", "unsynced", "unknown", "syncing", "other_previous"],
+)
+def test_self_reference_cleanup_preserves_real_restore_requirements(
+    service, protection
+):
+    service.state("living-room")
+    service.db.execute(
+        "UPDATE device_state SET previous_image_id=1,managed_image_id=1 WHERE device_id=?",
+        ("living-room",),
+    )
+    device = service.registry.get("living-room").device()
+    if protection == "override":
+        service.db.execute(
+            "INSERT INTO overrides VALUES(?,?,?,?,?,?)",
+            ("active", "living-room", 1, 50, "2099-01-01", "2026-01-01"),
+        )
+    elif protection == "base":
+        service.db.execute(
+            "UPDATE device_state SET base_image_id=1 WHERE device_id=?",
+            ("living-room",),
+        )
+    elif protection == "unsynced":
+        device = device.model_copy(
+            update={
+                "current_content": device.current_content.model_copy(
+                    update={"synced": False}
+                )
+            }
+        )
+    elif protection in ("unknown", "syncing"):
+        operation = submit(service)
+        service._start_write(operation)
+        service.update(operation, protection.upper())
+    else:
+        service.db.execute(
+            "UPDATE device_state SET previous_image_id=2 WHERE device_id=?",
+            ("living-room",),
+        )
+    service.clear_self_restore_reference("living-room", device)
+    assert service.state("living-room")["previous_image_id"] == (
+        2 if protection == "other_previous" else 1
+    )
 
 
 def test_offline(service):

tests/test_external_photo_sources.py

@@ -222,3 +222,7 @@ def test_unreadable_source_is_forbidden_not_empty(
     response = client.get("/api/v1/photo-sources/family/images")
     assert response.status_code == 403
     assert response.json()["error"]["code"] == "FORBIDDEN"
+
+
+# Legacy algorithms remain covered; production filesystem access is tested separately.
+pytestmark = pytest.mark.usefixtures("legacy_photo_engine")

tests/test_gallery_thumbnail.py

@@ -0,0 +1,28 @@
+import io
+
+from PIL import Image
+
+
+def test_gallery_thumbnail_upgrades_existing_cache_and_reuses_it(client, settings):
+    cache = settings.data_dir / "cache"
+    original = cache / "living-room-1.original"
+    thumb = cache / "living-room-1-thumb.jpg"
+    Image.new("RGB", (1600, 1200), "blue").save(original, "JPEG")
+    Image.new("RGB", (300, 225), "blue").save(thumb, "JPEG")
+    url = "/api/v1/devices/living-room/images/1/file?thumbnail=true"
+    result = client.get(url)
+    assert result.status_code == 200
+    assert Image.open(io.BytesIO(result.content)).size == (860, 645)
+    modified = thumb.stat().st_mtime_ns
+    assert client.get(url).content == result.content
+    assert thumb.stat().st_mtime_ns == modified
+    assert len(list(cache.glob("living-room-1-thumb*"))) == 1
+    assert Image.open(original).size == (1600, 1200)
+
+
+def test_gallery_thumbnail_does_not_upscale_small_source(client, settings):
+    original = settings.data_dir / "cache" / "living-room-1.original"
+    Image.new("RGBA", (200, 400), (255, 0, 0, 255)).save(original, "PNG")
+    result = client.get("/api/v1/devices/living-room/images/1/file?thumbnail=true")
+    assert result.status_code == 200
+    assert Image.open(io.BytesIO(result.content)).size == (200, 400)

tests/test_interval_schedule.py

@@ -0,0 +1,30 @@
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from pydantic import ValidationError
+
+from pigway_frame_flow.errors import FlowError
+from pigway_frame_flow.models import Schedule
+from pigway_frame_flow.scheduler.engine import next_run
+
+
+@pytest.mark.parametrize("minutes", [1, 7, 60, 120, 420, 10080])
+def test_interval_crosses_calendar_boundaries(minutes):
+    start = datetime(2026, 10, 16, 23, 58, tzinfo=UTC)
+    schedule = Schedule(type="interval", interval_minutes=minutes)
+    first = datetime.fromisoformat(next_run(schedule, start))
+    assert first == start + timedelta(minutes=minutes)
+    assert datetime.fromisoformat(next_run(schedule, first)) == first + timedelta(
+        minutes=minutes
+    )
+
+
+@pytest.mark.parametrize("minutes", [0, -1, 10081])
+def test_invalid_interval(minutes):
+    with pytest.raises(ValidationError):
+        Schedule(type="interval", interval_minutes=minutes)
+
+
+def test_missing_interval_fails():
+    with pytest.raises(FlowError):
+        next_run(Schedule(type="interval"))

tests/test_local_cloud_library.py

@@ -1,5 +1,6 @@
 from io import BytesIO
 
+import pytest
 from PIL import Image
 
 from pigway_frame_flow.providers.photo_sources import PhotoSourceInput
@@ -168,3 +169,7 @@ def test_manual_display_does_not_replace_task_head(client, service, settings):
             "SELECT * FROM managed_cloud_uploads WHERE image_id=?", (second,)
         )
     )
+
+
+# Legacy algorithms remain covered; production filesystem access is tested separately.
+pytestmark = pytest.mark.usefixtures("legacy_photo_engine")

tests/test_photo_canvas.py

@@ -138,3 +138,7 @@ def test_auto_preview_uses_requested_device_not_default(
     assert op["status"] == "COMPLETED"
     with Image.open(BytesIO(client.get(op["result"]["url"]).content)) as image:
         assert image.size == (1200, 1600)
+
+
+# Legacy algorithms remain covered; production filesystem access is tested separately.
+pytestmark = pytest.mark.usefixtures("legacy_photo_engine")

tests/test_photo_captions.py

@@ -159,3 +159,7 @@ def test_oversized_synology_photo_uses_read_only_cached_preview(service, setting
         "synology", source.model_copy(update={"synology_previews": False})
     )
     assert service.photo_sources.catalog("synology") == []
+
+
+# Legacy algorithms remain covered; production filesystem access is tested separately.
+pytestmark = pytest.mark.usefixtures("legacy_photo_engine")

tests/test_photo_failures.py

@@ -1,3 +1,4 @@
+import pytest
 from PIL import Image
 
 from pigway_frame_flow.providers.photo_sources import PhotoSourceInput
@@ -101,3 +102,7 @@ def test_random_bad_images_bounded_to_five(client, service, settings, monkeypatc
         "SELECT write_started FROM operations WHERE id=?", (op["operation_id"],)
     )
     assert row["write_started"] == 0
+
+
+# Legacy algorithms remain covered; production filesystem access is tested separately.
+pytestmark = pytest.mark.usefixtures("legacy_photo_engine")

tests/test_photo_orientation.py

@@ -62,12 +62,16 @@ def test_cached_dimensions_invalidation_and_no_fallback(
         ),
     )
     assert len(oriented.catalog("family")) == 1
+    from pigway_frame_flow.providers.photo_sources import dimensions
+
     monkeypatch.setattr(
         "pigway_frame_flow.providers.photo_sources.dimensions",
         lambda *a: pytest.fail("unchanged dimensions should be cached"),
     )
     assert len(oriented.catalog("family", refresh=True)) == 1
-    monkeypatch.undo()
+    monkeypatch.setattr(
+        "pigway_frame_flow.providers.photo_sources.dimensions", dimensions
+    )
     Image.new("RGB", (50, 100)).save(settings.photo_root / "20240101 Day" / "wide.jpg")
     assert oriented.catalog("family", refresh=True) == []
     with pytest.raises(FlowError):
@@ -110,3 +114,7 @@ def test_orientation_validation_and_api(client, oriented):
         ).json()["error"]["code"]
         == "UNSUPPORTED_CAPABILITY"
     )
+
+
+# Legacy algorithms remain covered; production filesystem access is tested separately.
+pytestmark = pytest.mark.usefixtures("legacy_photo_engine")

tests/test_photo_paths.py

@@ -0,0 +1,59 @@
+import io
+
+from PIL import Image
+
+from pigway_frame_flow.models import PhotoSourceContent
+from pigway_frame_flow.providers.photo_sources import PhotoSourceInput
+
+
+def test_photo_path_survives_render_and_asset_listing(client, service, monkeypatch):
+    photos = service.photo_sources
+    photos.save(
+        "family",
+        PhotoSourceInput(
+            name="Family",
+            kind="synology-photos",
+            location=".",
+            nas_root_path="/volume1/photo",
+        ),
+    )
+    monkeypatch.setattr(photos.synology, "sid", lambda: "fixture")
+    monkeypatch.setattr(
+        photos.synology,
+        "items",
+        lambda *a, **kw: [
+            {
+                "id": 42,
+                "filename": "original.PNG",
+                "additional": {
+                    "folder": "/家庭/20190130",
+                    "resolution": {"width": 1600, "height": 1200},
+                },
+            }
+        ],
+    )
+    out = io.BytesIO()
+    Image.new("RGB", (1600, 1200)).save(out, "PNG")
+    monkeypatch.setattr(photos.synology, "download", lambda *a, **kw: out.getvalue())
+    assert (
+        photos.catalog("family")[0]["source_path"]
+        == "/volume1/photo/家庭/20190130/original.PNG"
+    )
+    asset = service.content_asset(
+        PhotoSourceContent(type="photo_source", source_id="family", item_id="42")
+    )
+    assert asset["source_path"] == "/volume1/photo/家庭/20190130/original.PNG"
+    assert client.get("/api/v1/assets").json()[0]["source_path"] == asset["source_path"]
+    assert (
+        client.get("/api/v1/assets/" + asset["asset_id"] + "/source").json()["source"][
+            "item_id"
+        ]
+        == "42"
+    )
+
+
+def test_missing_photo_path_is_not_invented(service):
+    out = io.BytesIO()
+    Image.new("RGB", (20, 20)).save(out, "JPEG")
+    asset = service.assets.put(out.getvalue(), "manual.jpg")
+    assert asset["source_path"] is None

tests/test_photo_resolution.py

@@ -0,0 +1,123 @@
+import io
+
+import pytest
+from PIL import Image
+
+from pigway_frame_flow.errors import FlowError
+from pigway_frame_flow.providers.photo_sources import PhotoSourceInput
+
+
+def test_minimum_resolution_filters_catalog_and_persists(
+    client, service, settings, legacy_photo_engine
+):
+    root = settings.data_dir.parent / "photos"
+    root.mkdir()
+    settings.photo_root = root
+    for name, size in [
+        ("small.jpg", (160, 120)),
+        ("wide.jpg", (800, 600)),
+        ("tall.jpg", (600, 800)),
+    ]:
+        Image.new("RGB", size).save(root / name)
+    response = client.put(
+        "/api/v1/photo-sources/family",
+        json={
+            "name": "Family",
+            "kind": "local",
+            "location": ".",
+            "minimum_short_edge": 600,
+            "minimum_long_edge": 800,
+        },
+    )
+    assert response.status_code == 200
+    assert response.json()["minimum_short_edge"] == 600
+    assert service.photo_sources.get("family").minimum_long_edge == 800
+    assert {x["name"] for x in service.photo_sources.catalog("family")} == {
+        "wide.jpg",
+        "tall.jpg",
+    }
+    response = client.put(
+        "/api/v1/photo-sources/family",
+        json={
+            "name": "Family",
+            "kind": "local",
+            "location": ".",
+        },
+    )
+    assert response.status_code == 200
+    assert len(service.photo_sources.catalog("family")) == 3
+
+
+def test_resolution_rejects_small_synology_preview(service, monkeypatch):
+    photos = service.photo_sources
+    photos.save(
+        "family",
+        PhotoSourceInput(
+            name="Family",
+            kind="synology-photos",
+            location=".",
+            minimum_short_edge=600,
+            minimum_long_edge=800,
+        ),
+    )
+    row = {"id": "1", "name": "photo.jpg"}
+    monkeypatch.setattr(photos, "catalog", lambda *args, **kwargs: [row])
+    photos.api_items["family"] = {"1": {}}
+    monkeypatch.setattr(photos.synology, "item_people", lambda *a, **kw: [])
+
+    def image(size):
+        out = io.BytesIO()
+        Image.new("RGB", size).save(out, "JPEG")
+        return out.getvalue()
+
+    monkeypatch.setattr(photos.synology, "download", lambda *a, **kw: image((300, 400)))
+    with pytest.raises(FlowError, match="minimum resolution"):
+        photos.read("family", "1")
+    monkeypatch.setattr(photos.synology, "download", lambda *a, **kw: image((800, 600)))
+    assert photos.read("family", "1")[1] == "photo.jpg"
+
+
+def test_minimum_resolution_rejects_negative_value(client):
+    response = client.put(
+        "/api/v1/photo-sources/family",
+        json={
+            "name": "Family",
+            "kind": "synology-photos",
+            "location": ".",
+            "minimum_short_edge": -1,
+        },
+    )
+    assert response.status_code == 422
+
+
+def test_synology_metadata_resolution_filters_before_catalog_limit(
+    client, service, monkeypatch
+):
+    photos = service.photo_sources
+    monkeypatch.setattr(photos.synology, "sid", lambda: "fixture")
+    rows = [
+        {
+            "id": i,
+            "filename": f"{i}.jpg",
+            "additional": {
+                "folder": "/family",
+                "resolution": {"width": w, "height": h},
+            },
+        }
+        for i, w, h in [(1, 300, 400), (2, 800, 600), (3, 0, 0)]
+    ]
+    monkeypatch.setattr(photos.synology, "items", lambda *a, **kw: rows)
+    response = client.put(
+        "/api/v1/photo-sources/family",
+        json={
+            "name": "Family",
+            "kind": "synology-photos",
+            "location": ".",
+            "minimum_short_edge": 600,
+            "minimum_long_edge": 800,
+            "catalog_limit": 1,
+        },
+    )
+    assert response.status_code == 200
+    assert response.json()["minimum_long_edge"] == 800
+    assert [x["id"] for x in photos.catalog("family")] == ["2"]

tests/test_photo_sources.py

@@ -1,3 +1,6 @@
+import pytest
+
+
 def test_uploaded_photos_exclude_generated_templates_before_limit(client, service):
     photo = service.assets.put(b"fixture", "family.jpg", "images")
     for _ in range(5):
@@ -66,3 +69,7 @@ def test_multiple_sources_keep_separate_people_and_folder_settings(
     assert service.photo_sources.get("travel").model_dump() == before
     assert service.photo_sources.get("family").person_ids == [3]
     assert service.photo_sources.get("travel").person_ids == [2]
+
+
+# Legacy algorithms remain covered; production filesystem access is tested separately.
+pytestmark = pytest.mark.usefixtures("legacy_photo_engine")

tests/test_photo_watermark.py

@@ -1,12 +1,39 @@
 from io import BytesIO
 
 import pytest
-from PIL import Image
+from PIL import Image, ImageDraw
 
 from pigway_frame_flow.renderers.photo_caption import render_captioned_photo
 from pigway_frame_flow.renderers.photo_layout import PhotoLayout, WatermarkLayout
 
 
+def test_watermark_omits_raw_filename_and_includes_recognized_people(
+    service, monkeypatch
+):
+    drawn = []
+    original = ImageDraw.ImageDraw.text
+
+    def text(draw, xy, value, *args, **kwargs):
+        drawn.append(value)
+        return original(draw, xy, value, *args, **kwargs)
+
+    monkeypatch.setattr(ImageDraw.ImageDraw, "text", text)
+    stream = BytesIO()
+    Image.new("RGB", (160, 120), "blue").save(stream, "JPEG")
+    render_captioned_photo(
+        stream.getvalue(),
+        {
+            "date": "2026-10-17",
+            "title": "Family",
+            "filename": "one.jpg",
+            "people": "Alice & Bob",
+        },
+        service.renderer.font,
+        size=(1600, 1200),
+    )
+    assert drawn == ["2026-10-17 · Alice & Bob · Family"]
+
+
 @pytest.mark.parametrize("size", [(1600, 1200), (1200, 1600)])
 @pytest.mark.parametrize("fit", ["contain", "cover", "smart"])
 def test_watermark_has_no_letterboxing(service, size, fit):

tests/test_photos_api_boundary.py

@@ -0,0 +1,23 @@
+import json
+
+
+def test_filesystem_source_cannot_be_created(client):
+    response = client.put(
+        "/api/v1/photo-sources/legacy",
+        json={"name": "NAS directory", "kind": "local", "location": "."},
+    )
+    assert response.status_code == 403
+    assert "Filesystem photo sources are disabled" in response.text
+
+
+def test_persisted_filesystem_source_cannot_be_read(client, service):
+    service.db.execute(
+        "INSERT INTO app_config(key,payload) VALUES (?,?)",
+        (
+            "photo_source:legacy",
+            json.dumps({"name": "Legacy", "kind": "local", "location": "."}),
+        ),
+    )
+    response = client.get("/api/v1/photo-sources/legacy/images")
+    assert response.status_code == 403
+    assert "Filesystem photo sources are disabled" in response.text

tests/test_production_bootstrap.py

@@ -248,18 +248,14 @@ def test_actual_verify_rejects_ready_smoke_and_commit_failure(
         tool.verify(config)
 
 
-def test_workflow_bootstrap_manual_only_and_ci_namespace_separate(tool):
+def test_retired_workflow_has_no_bootstrap_and_ci_namespace_separate(tool):
     from pathlib import Path
 
     import yaml
 
     root = Path(__file__).parents[1]
     workflow = yaml.safe_load((root / ".github/workflows/verify.yml").read_text())
-    inputs = workflow[True]["workflow_dispatch"]["inputs"]["deploy_action"]
-    assert inputs["options"] == ["plan", "bootstrap", "deploy", "rollback"]
-    assert inputs["default"] == "plan"
-    assert workflow["jobs"]["deploy"]["needs"] == "verify"
-    assert "success()" in workflow["jobs"]["deploy"]["if"]
+    assert set(workflow["jobs"]) == {"verify"}
     tool.env["PROD_PROJECT"] = "ffci-invalid"
     with pytest.raises(ValueError):
         tool.settings()

tests/test_production_deploy.py

@@ -164,21 +164,14 @@ def test_activate_escapes_dollar_secrets_and_never_down(tool, monkeypatch):
     assert len(calls) == 2 and "up" in calls[1] and "--no-build" in calls[1]
 
 
-def test_workflow_deploy_is_verify_gated_and_manual_plan_default(tool):
+def test_workflow_verifies_without_legacy_production_deploy(tool):
     import yaml
 
     workflow = yaml.safe_load(
         (Path(__file__).parents[1] / ".github/workflows/verify.yml").read_text()
     )
-    job = workflow["jobs"]["deploy"]
-    assert job["needs"] == "verify" and "success()" in job["if"]
-    assert "refs/heads/main" in job["if"] and "pull_request" not in job["if"]
-    assert job["env"]["PROD_DEPLOY_ENABLED"] == "${{ vars.PROD_DEPLOY_ENABLED }}"
-    assert (
-        workflow[True]["workflow_dispatch"]["inputs"]["deploy_action"]["default"]
-        == "plan"
-    )
-    assert job["steps"][-1]["if"] == "always()"
+    assert set(workflow["jobs"]) == {"verify"}
+    assert workflow[True]["workflow_dispatch"] is None
 
 
 def test_recovery_handles_missing_or_crashed_production_container(tool, monkeypatch):
@@ -311,3 +304,24 @@ def test_image_retention_failure_does_not_fail_verified_deploy(
     output = capsys.readouterr().out
     assert "cleanup deferred" in output
     assert "private diagnostic" not in output
+
+
+def test_retired_nas_target_is_rejected(tool):
+    tool.env["PROD_DATA_DIR"] = "/volume2/docker/pigway-frame-flow/data"
+    with pytest.raises(ValueError, match="retired"):
+        tool.settings()
+
+
+def test_preflight_rejects_legacy_photo_mount(tool, monkeypatch):
+    old = existing(tool)
+    old["Mounts"].append(
+        {
+            "Type": "bind",
+            "Source": "/volume1/photo",
+            "Destination": "/photos",
+            "RW": False,
+        }
+    )
+    monkeypatch.setattr(tool, "inspect", lambda _: old)
+    with pytest.raises(ValueError, match="retired"):
+        tool.preflight()

tests/test_publication_security.py

@@ -6,10 +6,10 @@ def test_external_forks_do_not_execute_on_nas_runner():
     assert (
         "github.event.pull_request.head.repo.full_name == github.repository" in workflow
     )
-    assert "needs: verify" in workflow
+    assert "python scripts/production-deploy.py" not in workflow
 
 
-def test_private_production_configuration_uses_secrets():
+def test_verification_runner_receives_no_production_configuration():
     workflow = Path(".github/workflows/verify.yml").read_text()
     for key in (
         "PROD_DATA_DIR",
@@ -19,7 +19,7 @@ def test_private_production_configuration_uses_secrets():
         "SYNOLOGY_PHOTOS_URL",
         "SYNOLOGY_PHOTOS_CERT_SHA256",
     ):
-        assert "${{ secrets." + key + " }}" in workflow
+        assert "${{ secrets." + key + " }}" not in workflow
         assert "${{ vars." + key + " }}" not in workflow
 
 
@@ -28,7 +28,7 @@ def test_actions_downloads_do_not_depend_on_personal_server():
 
     workflow = Path(".github/workflows/verify.yml").read_text()
     actions = re.findall(r"uses:\s*(\S+)", workflow)
-    assert len(actions) == 4
+    assert len(actions) == 2
     for action in actions:
         assert re.fullmatch(
             r"https://github\.com/actions/(checkout|setup-python)@[0-9a-f]{40}",

tests/test_retention.py

@@ -172,3 +172,7 @@ def test_first_cleanup_runs_after_recent_host_boot(
         ]
         == 1
     )
+
+
+# Legacy algorithms remain covered; production filesystem access is tested separately.
+pytestmark = pytest.mark.usefixtures("legacy_photo_engine")

tests/test_server_release.py

@@ -0,0 +1,73 @@
+"""Production release preflight must reject unsafe inherited container settings."""
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture
+def release_tool():
+    spec = importlib.util.spec_from_file_location(
+        "server_release", Path(__file__).parents[1] / "scripts/server-release.py"
+    )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+@pytest.mark.parametrize(
+    "unsafe", ["mock", "writes", "photos", "system_disk", "root", "caps"]
+)
+def test_release_rejects_unsafe_runtime(release_tool, monkeypatch, unsafe):
+    container = {
+        "Config": {
+            "User": "10333:10333",
+            "Env": [
+                "KOKONNA_MOCK=false",
+                "KOKONNA_WRITE_ENABLED=true",
+                "BUILD_COMMIT=test",
+            ],
+        },
+        "State": {"Running": True},
+        "HostConfig": {"ReadonlyRootfs": True, "CapDrop": ["ALL"]},
+        "Mounts": [
+            {"Destination": "/data", "Source": str(release_tool.APP / "data")},
+            {"Destination": "/config", "Source": str(release_tool.APP / "config")},
+        ],
+    }
+    if unsafe == "mock":
+        container["Config"]["Env"][0] = "KOKONNA_MOCK=true"
+    elif unsafe == "writes":
+        container["Config"]["Env"][1] = "KOKONNA_WRITE_ENABLED=false"
+    elif unsafe == "photos":
+        container["Mounts"].append(
+            {"Destination": "/photos", "Source": "/volume1/photo"}
+        )
+    elif unsafe == "system_disk":
+        container["Mounts"][0]["Source"] = "/var/lib/frame-flow"
+    elif unsafe == "root":
+        container["Config"]["User"] = "root"
+    else:
+        container["HostConfig"]["CapDrop"] = []
+    monkeypatch.setattr(release_tool, "inspect", lambda: container)
+    with pytest.raises(AssertionError):
+        release_tool.verify_runtime("test")
+
+
+def test_release_readiness_retries_on_actual_listener(release_tool, monkeypatch):
+    import io
+    import urllib.error
+
+    calls = []
+
+    def listener(url, timeout):
+        calls.append(url)
+        if url != "http://192.0.2.10:81/ready" or len(calls) == 1:
+            raise urllib.error.URLError("Connection refused during restart")
+        return io.BytesIO(b'{"status":"ready"}')
+
+    monkeypatch.setattr(release_tool.urllib.request, "urlopen", listener)
+    monkeypatch.setattr(release_tool.time, "sleep", lambda _: None)
+    release_tool.wait_ready()
+    assert len(calls) == 2

tests/test_synology_photos.py

@@ -152,3 +152,7 @@ def test_people_api_auth_and_secret_response(client, service, monkeypatch):
     assert r.status_code == 422 and "input" not in r.text
     client.headers.pop("Authorization")
     assert client.get("/api/v1/integrations/synology-photos/people").status_code == 401
+
+
+# Legacy algorithms remain covered; production filesystem access is tested separately.
+pytestmark = pytest.mark.usefixtures("legacy_photo_engine")

tests/test_synology_photos_api.py

@@ -0,0 +1,403 @@
+import hashlib
+import io
+import json
+from concurrent.futures import ThreadPoolExecutor
+
+import pytest
+from PIL import Image
+
+from pigway_frame_flow.errors import FlowError
+from pigway_frame_flow.providers.photo_sources import PhotoSourceInput
+from pigway_frame_flow.providers.photos_cache import PhotosCache
+from pigway_frame_flow.providers.synology_photos import SynologyPhotos
+
+
+def jpeg(color="red"):
+    out = io.BytesIO()
+    Image.new("RGB", (24, 16), color).save(out, "JPEG")
+    return out.getvalue()
+
+
+def session(settings, value="fixture-session"):
+    settings.config_dir.mkdir(parents=True, exist_ok=True)
+    (settings.config_dir / "synology-photos-session.json").write_text(
+        json.dumps({"sid": value})
+    )
+
+
+def row(id, folder="/family", name="same.jpg"):
+    return {
+        "id": id,
+        "filename": name,
+        "type": "photo",
+        "filesize": 9000,
+        "indexed_time": 42,
+        "additional": {
+            "folder": folder,
+            "resolution": {"width": 24, "height": 16},
+            "thumbnail": {"unit_id": id, "cache_key": "fixture-key"},
+        },
+    }
+
+
+@pytest.mark.parametrize(
+    "space,prefix", [("shared", "SYNO.FotoTeam"), ("personal", "SYNO.Foto")]
+)
+@pytest.mark.parametrize("mode,expected", [("any", ["1", "2", "3"]), ("all", ["2"])])
+def test_api_identity_selection(settings, monkeypatch, space, prefix, mode, expected):
+    session(settings)
+    p = SynologyPhotos(settings)
+    monkeypatch.setattr(p, "people", lambda space: [{"id": 10}, {"id": 20}])
+
+    def pages(api, version, **params):
+        assert api == prefix + ".Browse.Item"
+        return [row(i) for i in ([1, 2] if params["person_id"] == 10 else [2, 3])]
+
+    monkeypatch.setattr(p, "pages", pages)
+    assert [str(x["id"]) for x in p.items([10, 20], mode, space=space)] == expected
+    with pytest.raises(FlowError):
+        p.items([99], space=space)
+
+
+def test_people_pagination_does_not_stop_at_500(settings, monkeypatch):
+    session(settings)
+    p = SynologyPhotos(settings)
+    calls = []
+
+    def request(api, method, version, **params):
+        calls.append(params["offset"])
+        return {
+            "list": [
+                {"id": i}
+                for i in range(params["offset"], min(1334, params["offset"] + 500))
+            ]
+        }
+
+    monkeypatch.setattr(p, "request", request)
+    assert len(p.people()) == 1334
+    assert calls == [0, 500, 1000]
+
+
+def test_caption_people_use_actual_membership_and_cache(settings, monkeypatch):
+    session(settings)
+    provider = SynologyPhotos(settings)
+    monkeypatch.setattr(
+        provider,
+        "people",
+        lambda space: [
+            {"id": 1, "name": "Alice", "named": True},
+            {"id": 2, "name": "Bob", "named": True},
+            {"id": 3, "name": "3", "named": False},
+        ],
+    )
+    calls = []
+
+    def pages(api, version, **params):
+        calls.append(api)
+        return [{"id": params["person_id"]}, {"id": 10}]
+
+    monkeypatch.setattr(provider, "pages", pages)
+    assert provider.item_people(1) == ["Alice"]
+    assert provider.item_people(10) == ["Alice", "Bob"]
+    assert provider.item_people(99) == []
+    assert calls == ["SYNO.FotoTeam.Browse.Item"] * 2
+    assert provider.item_people(10, space="personal") == ["Alice", "Bob"]
+    assert calls[-2:] == ["SYNO.Foto.Browse.Item"] * 2
+
+
+@pytest.mark.parametrize("labels_available", [True, False])
+def test_api_caption_keeps_folder_and_optional_people_without_filename(
+    service, settings, monkeypatch, labels_available
+):
+    session(settings)
+    provider = service.photo_sources
+    monkeypatch.setattr(
+        provider.synology,
+        "items",
+        lambda *a, **k: [row(1, "/20261017 Family@Park", "one.jpg")],
+    )
+    monkeypatch.setattr(provider.synology, "download", lambda *a, **k: jpeg())
+
+    def names(*a, **k):
+        if not labels_available:
+            raise FlowError("CLOUD_UNAVAILABLE", "unavailable", 502)
+        return ["Alice", "Bob"]
+
+    monkeypatch.setattr(provider.synology, "item_people", names)
+    provider.save(
+        "captions",
+        PhotoSourceInput(
+            name="Family", kind="synology-photos", location=".", folder_caption=True
+        ),
+    )
+    _, _, caption = provider.read("captions", "1")
+    assert caption["date"] == "2026-10-17"
+    assert caption["title"] == "Family"
+    assert "filename" not in caption
+    assert caption.get("people", "") == ("Alice & Bob" if labels_available else "")
+
+
+def test_source_without_mount_pagination_scope_and_session(
+    client, service, settings, monkeypatch
+):
+    session(settings)
+    settings.photo_root = settings.data_dir / "must-not-exist"
+    p = service.photo_sources
+    monkeypatch.setattr(
+        p.synology,
+        "items",
+        lambda *a, **k: [row(1), row(2, "/family/child"), row(3, "/other")],
+    )
+    monkeypatch.setattr(p.synology, "download", lambda *a, **k: jpeg())
+    source = PhotoSourceInput(
+        name="API",
+        kind="synology-photos",
+        location="family",
+        people_filter=True,
+        person_ids=[10],
+        orientation="landscape",
+    )
+    p.save("api", source)
+    response = client.get("/api/v1/photo-sources/api/images?offset=1&limit=1")
+    assert response.status_code == 200, response.text
+    assert response.json()["total"] == 2
+    assert response.json()["items"][0]["id"] == "2"
+    assert "cache_key" not in response.text and "_photos" not in response.text
+    data, name, _ = p.read("api", "1")
+    Image.open(io.BytesIO(data)).load()
+    assert name == "same.jpg" and not settings.photo_root.exists()
+    with pytest.raises(FlowError):
+        p.read("api", "3")
+    p.synology.disconnect()
+    with pytest.raises(FlowError) as error:
+        p.catalog("api")
+    assert error.value.status == 409
+    session(settings, "different-account")
+    monkeypatch.setattr(p.synology, "items", lambda *a, **k: [])
+    assert p.catalog("api") == []
+
+
+def test_existing_local_sources_are_not_silently_converted(service, settings):
+    settings.photo_root = settings.data_dir / "missing"
+    with pytest.raises(FlowError):
+        service.photo_sources.save(
+            "local", PhotoSourceInput(name="Legacy", kind="local", location=".")
+        )
+    with pytest.raises(FlowError):
+        service.photo_sources.save(
+            "api",
+            PhotoSourceInput(name="API", kind="synology-photos", location="../secrets"),
+        )
+
+
+def test_cache_coalesces_concurrency_and_recovers_partial_files(settings):
+    settings.photos_cache_bytes = 2000
+    settings.max_bytes = 1000
+    cache = PhotosCache(settings)
+
+    def download(handle, cap, deadline):
+        handle.write(jpeg())
+
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        results = list(pool.map(lambda _: cache.read("one", download), range(8)))
+    assert all(x == jpeg() for x in results)
+    assert cache.downloads == 1 and cache.hits == 7
+    (cache.root / "interrupted.part").write_bytes(b"partial")
+    cache.read("two", download)
+    cache.read("three", download)
+    assert sum(p.stat().st_size for p in cache.root.glob("*.image")) <= 2000
+    assert not list(cache.root.glob("*.part"))
+    assert cache.read("three", download) == jpeg()
+
+
+@pytest.mark.parametrize("failure", ["interrupt", "invalid", "oversize"])
+def test_cache_failures_never_commit(settings, failure):
+    settings.max_bytes = 1000
+    cache = PhotosCache(settings)
+
+    def download(handle, cap, deadline):
+        handle.write(
+            jpeg()
+            if failure == "interrupt"
+            else b"wrong"
+            if failure == "invalid"
+            else b"x" * 1001
+        )
+        if failure == "interrupt":
+            raise TimeoutError()
+
+    with pytest.raises(FlowError):
+        cache.read("bad", download)
+    assert not list(cache.root.glob("*.part"))
+    assert not list(cache.root.glob("*.image"))
+
+
+def transport(
+    settings, monkeypatch, *, bad_pin=False, expired=False, interrupted=False
+):
+    monkeypatch.setenv("SYNOLOGY_PHOTOS_URL", "https://nas.test:9115")
+    monkeypatch.setenv(
+        "SYNOLOGY_PHOTOS_CERT_SHA256",
+        "a" * 64 if bad_pin else hashlib.sha256(b"certificate").hexdigest(),
+    )
+    sent = []
+
+    class Socket:
+        def getpeercert(self, **kw):
+            return b"certificate"
+
+    class Response:
+        status = 200
+
+        def __init__(self):
+            self.buffer = io.BytesIO(
+                b'{"success":false,"error":{"code":106}}' if expired else jpeg()
+            )
+
+        def getheader(self, name):
+            return (
+                ("application/json" if expired else "image/jpeg")
+                if name == "Content-Type"
+                else str(len(self.buffer.getvalue()))
+            )
+
+        def read(self, size):
+            if interrupted:
+                raise TimeoutError()
+            return self.buffer.read(size)
+
+    class Connection:
+        sock = Socket()
+
+        def __init__(self, *a, **kw):
+            pass
+
+        def connect(self):
+            pass
+
+        def request(self, *args):
+            sent.append(args)
+
+        def getresponse(self):
+            return Response()
+
+        def close(self):
+            pass
+
+    monkeypatch.setattr("http.client.HTTPSConnection", Connection)
+    session(settings)
+    return SynologyPhotos(settings), sent
+
+
+def test_binary_transport_pin_before_secret_and_read_allowlist(settings, monkeypatch):
+    p, sent = transport(settings, monkeypatch, bad_pin=True)
+    with pytest.raises(FlowError):
+        p.download(row(1))
+    assert not sent
+    with pytest.raises(FlowError):
+        p._download(
+            "SYNO.FotoTeam.Browse.Item",
+            "delete",
+            {},
+            "fixture",
+            io.BytesIO(),
+            1000,
+            100,
+        )
+    assert not sent
+
+
+def test_download_decodes_cache_reuse_and_rendition_rejection(settings, monkeypatch):
+    p, sent = transport(settings, monkeypatch)
+    assert p.download(row(1)) == jpeg()
+    assert p.download(row(1)) == jpeg()
+    assert len(sent) == 1
+    assert "SYNO.FotoTeam.Thumbnail" in sent[0][2]
+    assert p.download(row(1), space="personal") == jpeg()
+    assert len(sent) == 2
+    session(settings, "different-session")
+    assert p.download(row(1)) == jpeg()
+    assert len(sent) == 3
+    with pytest.raises(FlowError):
+        p.download(row(1), rendition="original")
+
+
+def test_download_session_error_and_interruption(settings, monkeypatch):
+    p, _ = transport(settings, monkeypatch, expired=True)
+    with pytest.raises(FlowError) as error:
+        p.download(row(1))
+    assert error.value.status == 409
+    assert not p.path.exists()
+    assert not list(p.image_cache.root.glob("*.part"))
+    p, _ = transport(settings, monkeypatch, interrupted=True)
+    with pytest.raises(FlowError):
+        p.download(row(1))
+    assert not list(p.image_cache.root.glob("*.part"))
+
+
+def cache_process(settings, marker):
+    cache = PhotosCache(settings)
+
+    def download(handle, cap, deadline):
+        with open(marker, "ab") as counter:
+            counter.write(b"download\n")
+        handle.write(jpeg())
+
+    assert cache.read("shared-process-key", download) == jpeg()
+
+
+def test_cache_coalesces_across_processes(settings, tmp_path):
+    import multiprocessing
+
+    context = multiprocessing.get_context("spawn")
+    marker = tmp_path / "downloads"
+    processes = [
+        context.Process(target=cache_process, args=(settings, marker)) for _ in range(3)
+    ]
+    for process in processes:
+        process.start()
+    for process in processes:
+        process.join(15)
+        assert process.exitcode == 0
+    assert marker.read_bytes() == b"download\n"
+
+
+def test_explicit_offline_conversion_preserves_task_reference(service, settings):
+    import importlib.util
+    from pathlib import Path
+
+    spec = importlib.util.spec_from_file_location(
+        "photos_migration", Path(__file__).parents[1] / "scripts/migrate-photos-api.py"
+    )
+    migration = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(migration)
+    # The production service uses this filename; inspect the fixture connection
+    # rather than modifying an unrelated database.
+    path = Path(service.db.conn.execute("PRAGMA database_list").fetchone()[2])
+    source = PhotoSourceInput(
+        name="Existing",
+        kind="local",
+        location="family",
+        people_filter=True,
+        person_ids=[5],
+        synology_previews=True,
+        people_space="personal",
+        person_match="all",
+    )
+    service.db.execute(
+        "INSERT INTO app_config VALUES(?,?)",
+        ("photo_source:existing", source.model_dump_json()),
+    )
+    before = service.photo_sources.get("existing")
+    assert not migration.convert(path, ["existing"])["applied"]
+    assert service.photo_sources.get("existing") == before
+    result = migration.convert(path, ["existing"], apply=True)
+    assert Path(result["backup"]).is_file()
+    after = service.photo_sources.get("existing")
+    assert after.kind == "synology-photos" and not after.synology_previews
+    assert (
+        after.person_ids == [5]
+        and after.people_space == "personal"
+        and after.person_match == "all"
+        and after.location == "family"
+    )

tests/test_upload_retries.py

@@ -0,0 +1,154 @@
+from datetime import UTC, datetime, timedelta
+
+from pigway_frame_flow.errors import ErrorCode, FlowError
+from pigway_frame_flow.models import JobInput
+from pigway_frame_flow.scheduler.engine import Scheduler
+
+
+def failed_job(app, service, monkeypatch):
+    scheduler = app.state.scheduler
+    job = scheduler.save_job(
+        JobInput(
+            name="Retry",
+            schedule={"type": "interval", "interval_minutes": 120},
+            source={"type": "template", "template": "quote"},
+        )
+    )
+    now = datetime.now(UTC)
+    service.db.execute(
+        "UPDATE jobs SET next_run=? WHERE id=?",
+        ((now - timedelta(seconds=1)).isoformat(), job["id"]),
+    )
+    driver = service.registry.get("living-room")
+    upload = driver.upload
+
+    def fail(*a):
+        raise FlowError(ErrorCode.UPLOAD_FAILED, "Rejected", 502)
+
+    monkeypatch.setattr(driver, "upload", fail)
+    scheduler.tick(now)
+    service.process_one()
+    scheduler.tick(now + timedelta(seconds=1))
+    return scheduler, job, now, driver, upload
+
+
+def test_five_backoffs_then_one_scheduled_failure_regenerates(
+    app, service, monkeypatch, client
+):
+    scheduler, job, now, driver, upload = failed_job(app, service, monkeypatch)
+    policy = scheduler.upload_retries
+    plan = policy.load(job["id"])
+    asset = plan["asset_id"]
+    path = service.assets.path(asset)
+    original = path.read_bytes()
+    assert client.get("/api/v1/assets").json() == []
+    assert (
+        service.db.one("SELECT kind FROM assets WHERE id=?", (asset,))["kind"]
+        == "cache"
+    )
+    times = [datetime.fromisoformat(x) for x in plan["times"]]
+    gaps = [(times[0] - now).total_seconds()] + [
+        (b - a).total_seconds() for a, b in zip(times, times[1:], strict=False)
+    ]
+    assert gaps == sorted(gaps) and len(times) == 5
+    assert times[-1] < datetime.fromisoformat(plan["deadline"])
+    for number, when in enumerate(times, 1):
+        scheduler.tick(when + timedelta(milliseconds=1))
+        attempt = policy.load(job["id"])
+        assert attempt["count"] == number
+        op = service.operation(attempt["active"])
+        assert (
+            service.db.one(
+                "SELECT payload FROM operations WHERE id=?", (op["operation_id"],)
+            )["payload"].find(asset)
+            >= 0
+        )
+        service.process_one()
+        assert path.read_bytes() == original
+    assert len(service.db.all("SELECT * FROM job_runs")) == 1
+    # The plan survives a process restart, without resetting the five-attempt cap.
+    scheduler = Scheduler(service)
+    deadline = datetime.fromisoformat(plan["deadline"])
+    scheduler.tick(deadline + timedelta(milliseconds=1))
+    planned = scheduler.upload_retries.load(job["id"])
+    assert planned["phase"] == "scheduled_running"
+    service.process_one()
+    scheduler.tick(deadline + timedelta(seconds=1))
+    replacement = scheduler.upload_retries.load(job["id"])
+    assert replacement["phase"] == "replacement"
+    assert not path.exists()
+    assert service.db.one("SELECT id FROM assets WHERE id=?", (asset,)) is None
+    monkeypatch.setattr(driver, "upload", upload)
+    service.process_one()
+    service.sync()
+    op = service.operation(replacement["active"])
+    assert op["status"] == "COMPLETED"
+    assert op["result"]["rendered_asset_id"] != asset
+    assert len(service.db.all("SELECT * FROM job_runs")) == 2
+
+
+def test_retry_success_cancels_rest_and_keeps_schedule(app, service, monkeypatch):
+    scheduler, job, now, driver, upload = failed_job(app, service, monkeypatch)
+    policy = scheduler.upload_retries
+    plan = policy.load(job["id"])
+    deadline = service.db.one("SELECT next_run FROM jobs WHERE id=?", (job["id"],))[
+        "next_run"
+    ]
+    monkeypatch.setattr(driver, "upload", upload)
+    when = datetime.fromisoformat(plan["times"][0]) + timedelta(milliseconds=1)
+    scheduler.tick(when)
+    operation = policy.load(job["id"])["active"]
+    service.process_one()
+    service.sync()
+    scheduler.tick(when + timedelta(seconds=1))
+    assert policy.load(job["id"]) is None
+    assert service.operation(operation)["status"] == "COMPLETED"
+    assert (
+        service.db.one("SELECT next_run FROM jobs WHERE id=?", (job["id"],))["next_run"]
+        == deadline
+    )
+    assert (
+        service.db.one("SELECT kind FROM assets WHERE id=?", (plan["asset_id"],))[
+            "kind"
+        ]
+        == "generated"
+    )
+    assert driver.client.uploads == 1
+
+
+def test_expired_queued_retry_never_uploads(app, service, monkeypatch):
+    scheduler, job, now, driver, upload = failed_job(app, service, monkeypatch)
+    policy = scheduler.upload_retries
+    plan = policy.load(job["id"])
+    scheduler.tick(datetime.fromisoformat(plan["times"][0]) + timedelta(milliseconds=1))
+    plan = policy.load(job["id"])
+    plan["deadline"] = (datetime.now(UTC) - timedelta(seconds=1)).isoformat()
+    policy.save(job["id"], plan)
+
+    def unexpected(*a):
+        raise AssertionError("Expired retry must never upload")
+
+    monkeypatch.setattr(driver, "upload", unexpected)
+    service.process_one()
+    operation = service.operation(plan["active"])
+    assert operation["status"] == "FAILED"
+    assert operation["error"]["details"]["reason"] == "RETRY_WINDOW_CLOSED"
+    assert service.assets.path(plan["asset_id"]).exists()
+
+
+def test_lost_response_is_reconciled_before_retry_without_duplicate(
+    app, service, monkeypatch
+):
+    scheduler, job, now, driver, upload = failed_job(app, service, monkeypatch)
+    policy = scheduler.upload_retries
+    plan = policy.load(job["id"])
+    asset = service.assets.info(plan["asset_id"])
+    monkeypatch.setattr(driver, "upload", upload)
+    # The original request reached the cloud, but its response was lost.
+    driver.upload(service.assets.path(plan["asset_id"]), asset["name"])
+    service.update(plan["root"], "UNKNOWN")
+    scheduler.tick(datetime.fromisoformat(plan["times"][0]) + timedelta(milliseconds=1))
+    scheduler.tick(datetime.fromisoformat(plan["times"][0]) + timedelta(seconds=1))
+    assert service.operation(plan["root"])["status"] == "COMPLETED"
+    assert policy.load(job["id"]) is None
+    assert driver.client.uploads == 1