release: v0.1.16 with compact layouts and corrected settings columns [skip ci]

.dockerignore

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

.env.example

@@ -2,7 +2,9 @@ TZ=Asia/Shanghai
 # Default local access. For NAS LAN access set this to the NAS LAN IP (recommended)
 # or explicitly 0.0.0.0. No router, reverse proxy or firewall rules are modified.
 WEB_BIND=127.0.0.1
-WEB_PORT=18787
+WEB_PORT=6005
+# Display name of the NAS/server storing the local gallery.
+FRAME_FLOW_STORAGE_NAME=NAS
 KOKONNA_MOCK=true
 KOKONNA_WRITE_ENABLED=false
 KOKONNA_API_KEY=

.github/workflows/verify.yml

@@ -1,14 +1,10 @@
 name: Verify Frame Flow
 on:
   push:
+    # Branch verification gates releases; tags do not duplicate the same build.
+    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.
@@ -45,53 +41,5 @@ jobs:
             python scripts/ci-compose-verify.py --cleanup
           fi
 
-  deploy:
+# Production moved to Ubuntu Server. Release manually with scripts/server-release.py;
-    needs: verify
+# the shared NAS runner performs isolated verification only.
-    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 }}
-      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

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
 
@@ -22,7 +22,7 @@ docker compose run --rm --no-deps -e PYTHONPATH=/app \
 docker compose up -d
 ```
 
-Open `http://127.0.0.1:18787` and sign in with the account you created. The browser uses an HttpOnly session cookie; it does not require an API token. Remembered sessions last 30 days. Change the password or sign out in Settings. `FRAME_FLOW_TOKEN` authenticates external API clients and is separate from the KoKonna API key.
+Open `http://127.0.0.1:6005` and sign in with the account you created. The browser uses an HttpOnly session cookie; it does not require an API token. Remembered sessions last 30 days. Change the password or sign out in Settings. `FRAME_FLOW_TOKEN` authenticates external API clients and is separate from the KoKonna API key.
 
 The published interface defaults to loopback. For LAN access, explicitly set `WEB_BIND` to your NAS LAN address and choose an available `WEB_PORT`. See [Synology deployment](docs/NAS.md), [build mirrors and caching](docs/BUILDING.md), and [Gitea deployment/rollback](docs/deployment/GITEA_CD.md). No firewall, router or reverse-proxy settings are changed automatically.
 
@@ -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).
@@ -90,4 +92,4 @@ Tests mock cloud/device calls. CI also verifies an isolated Docker build, readin
 
 Cloud synchronization does not prove the physical pixels refreshed. KoKonna cloud uploads activate immediately, so upload-only uses local staging. Native slideshow membership editing is unavailable; avoid running native and Frame Flow playback simultaneously. Smart cropping is a saliency heuristic, not guaranteed face detection. The service uses one worker and is not designed for multiple replicas. Browser OAuth, AI daily-art scheduling, additional calendar recurrence features and more device drivers remain roadmap items.
 
-Related projects: [PIGWay Device Agent](https://tea.pigway.com/way/pigway-device-agent) · [PIGWay Device Console](https://tea.pigway.com/way/pigway-device-console) · [PIGWay Yahboom Cooling HAT](https://tea.pigway.com/way/pigway-yahboom-cooling-hat)
+Related projects: [PIGWay Raspberry Pi Agent](https://tea.pigway.com/way/pigway-raspberry-pi-agent) · [PIGWay Device Console](https://tea.pigway.com/way/pigway-device-console) · [PIGWay Yahboom Cooling HAT](https://tea.pigway.com/way/pigway-yahboom-cooling-hat)

README.zh-CN.md

@@ -1,4 +1,4 @@
-# Pigway Frame Flow
+# PIGWay Frame Flow
 
 简体中文 | [English](README.md)
 
@@ -22,7 +22,7 @@ docker compose run --rm --no-deps -e PYTHONPATH=/app \
 docker compose up -d
 ```
 
-打开 `http://127.0.0.1:18787`，使用刚创建的账号登录。网页使用 HttpOnly 会话 Cookie，无需输入 API Token；勾选记住登录后会话有效期为 30 天，可在设置中修改密码或退出。`FRAME_FLOW_TOKEN` 用于外部 API 客户端鉴权，与 KoKonna API Key 分开。
+打开 `http://127.0.0.1:6005`，使用刚创建的账号登录。网页使用 HttpOnly 会话 Cookie，无需输入 API Token；勾选记住登录后会话有效期为 30 天，可在设置中修改密码或退出。`FRAME_FLOW_TOKEN` 用于外部 API 客户端鉴权，与 KoKonna API Key 分开。
 
 默认端口只绑定本机回环地址。需要局域网访问时，显式将 `WEB_BIND` 设置为 NAS 的局域网地址，并通过 `WEB_PORT` 选择空闲端口。参见[群晖部署](docs/NAS.md)、[构建镜像源与缓存](docs/BUILDING.md)和 [Gitea 部署与回滚](docs/deployment/GITEA_CD.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 兼容接口排版，以及从数据源自动选图拼接。
@@ -90,4 +92,4 @@ KoKonna 是支持的设备集成。本项目与 KoKonna 无隶属关系，也不
 
 云端同步不等于已确认物理屏幕刷新。KoKonna 云端上传会立即切换，因此“仅上传”使用本地暂存。官方接口不支持编辑原生轮播成员，应避免原生轮播与 Frame Flow 播放同时运行。smart 裁切采用显著性启发式，不保证识别人脸。当前服务使用单 Worker，不面向多副本部署。浏览器 OAuth、AI 每日艺术调度、更多日历重复规则及设备驱动仍属于后续计划。
 
-相关项目：[PIGWay Device Agent](https://tea.pigway.com/way/pigway-device-agent) · [PIGWay Device Console](https://tea.pigway.com/way/pigway-device-console) · [PIGWay Yahboom Cooling HAT](https://tea.pigway.com/way/pigway-yahboom-cooling-hat)
+相关项目：[PIGWay Raspberry Pi Agent](https://tea.pigway.com/way/pigway-raspberry-pi-agent) · [PIGWay Device Console](https://tea.pigway.com/way/pigway-device-console) · [PIGWay Yahboom Cooling HAT](https://tea.pigway.com/way/pigway-yahboom-cooling-hat)

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.16" 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
+      SYNOLOGY_PHOTOS_CACHE_BYTES: ${SYNOLOGY_PHOTOS_CACHE_BYTES:-268435456}
-    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

docker-compose.yml

@@ -17,12 +17,13 @@ services:
     init: true
     user: "10333:10333"
     ports:
-      - "${WEB_BIND:-127.0.0.1}:${WEB_PORT:-18787}:18787"
+      - "${WEB_BIND:-127.0.0.1}:${WEB_PORT:-6005}:18787"
     env_file: .env
     environment:
       TZ: Asia/Shanghai
       DATA_DIR: /data
       CONFIG_DIR: /config
+      FRAME_FLOW_STORAGE_NAME: ${FRAME_FLOW_STORAGE_NAME:-NAS}
     volumes:
       - ./data:/data
       - ./config:/config

docs/KOKONNA_RECOVERY.md

@@ -0,0 +1,61 @@
+# KoKonna 错误、重试与阻塞处理
+
+核对日期：2026-10-16。依据：[KoKonna OpenAPI 官方文档](https://kokonna.art/pages/openapi)、[Requests 异常定义](https://requests.readthedocs.io/en/latest/_modules/requests/exceptions/)。本页区分厂商契约与 Frame Flow 的本地策略；没有文档保证的行为不作为自动重发依据。
+
+## 官方接口契约
+
+- 设备 API Key 使用 Bearer 鉴权；单设备每分钟上限 20 次，请求超限返回 429。
+- 上传成功返回新图片 ID 和计数，并立即激活新图；接口不提供幂等键或上传状态查询契约。
+- 删除可能改变当前图片。切换与删除都不能视为天然可重放。
+- 404 可表示方法不存在；图片下载时也可表示目标图片不存在。
+- 500 既可能是通用服务故障，也可能明确表示设备密钥无效、图片不存在或图片 ID 参数错误。实现只匹配官方明确列出的签名，其他 500 不猜测是否产生副作用。
+- 上传请求体上限 50 MB；本服务原图限制仍为 20 MiB，并保留像素上限和 base64 检查。
+- 官方文档未承诺服务处理时长、超时后的取消、事务回滚或 Retry-After 返回；不能靠等待固定时间证明写入没有执行。
+- Requests 将连接建立超时定义为可安全重试；读取超时不提供相同保证。一般连接异常也不能推定请求未发送。
+
+## 已落实的本地策略
+
+| 结果 | 处理 | 自动重试 | 设备阻塞 |
+| --- | --- | --- | --- |
+| 未配置密钥 | CONFIG_REQUIRED | 无 | 无 |
+| 明确的设备密钥无效 | CONFIG_REQUIRED，保存固定错误分类 | 无 | 无 |
+| 明确的图片不存在 | NOT_FOUND | 无 | 无 |
+| 明确的图片 ID 参数错误 | INVALID_REQUEST | 无 | 无 |
+| 明确的方法不存在 | UNSUPPORTED_CAPABILITY | 无 | 无 |
+| 其他 HTTP 4xx 拒绝 | 保存状态码，结束失败 | 除 429 外无 | 无 |
+| 本地请求预算耗尽 | 等待预算窗口 | 同一请求最多 3 次尝试 | 不创建 UNKNOWN |
+| HTTP 429 | RATE_LIMITED，尊重服务端冷却时间 | 最多 3 次尝试 | 耗尽后失败，不创建 UNKNOWN |
+| ConnectTimeout | 确定请求未发送 | 读写均最多 3 次尝试 | 耗尽后失败，不创建 UNKNOWN |
+| 只读查询的临时网络错误、通用 5xx、无效 JSON | CLOUD_UNAVAILABLE | 最多 3 次尝试 | 不创建 UNKNOWN |
+| TLS 异常 | 保存固定分类 | 无 | 写请求仍保守标为 UNKNOWN |
+| 写请求读取超时、一般连接异常、通用 5xx | 无法确定写入结果 | 不重发，只读核对 | UNKNOWN，保留保护 |
+| 写请求无效响应或无有效上传 ID | 无法确认成功 | 不重发，只读核对 | UNKNOWN，保留保护 |
+
+“最多 3 次”包含首次请求，重试发生在同一传输请求内，不重新渲染、不重新执行整个操作。普通退避为 1、2 秒；每次实际请求都计入本地 18 次/分钟预算。429 优先使用 Retry-After 秒数或 HTTP 日期；缺失/无效时按 60 秒。单次等待不超过 60 秒，超过此值保留冷却并结束当前尝试，不提前请求。没有无限循环，也不在重启后重放不确定的写入。
+
+操作错误的 details 保存 attempts、retryable、write_outcome，以及 transport_error / http_status / failure_kind 等固定分类。不会保存异常原文、完整下载 URL、带密钥的厂商消息或响应正文。是否重试由结果类别决定，不能仅依据 HTTP 500。
+
+## 未知写入的核对与升级
+
+上传前记录资产、哈希、字节数、名称、上传前图库和时间。响应丢失后只读查找并校验唯一候选；图片相同且设备已同步才能记为成功。已证明上传、但设备持续停留原图时，沿用两次稳定观察的失败关闭规则。
+
+没有候选、候选不唯一、内容不符、设备未同步、查询失败或缺少历史证据，都有独立恢复原因。图库没有目标图片不等于厂商保证从未接受请求，因此不自动把它改为失败或重传。
+
+`GET /api/v1/operations/{operation_id}` 的 `recovery` 返回：
+
+- `state`：checking / manual_review / resolved。
+- `reason`：gallery_match_missing、gallery_match_ambiguous、content_mismatch、waiting_device_sync、target_mismatch、read_unavailable、reconciliation_error、missing_upload_evidence 或 manual_reconciliation_required。
+- `first_checked_at`、`last_checked_at`、`checks`、`requires_manual_review`。
+
+只读核对每条操作至多每分钟一次。操作持续未知超过 sync_timeout + 300 秒（默认约 15 分钟）时，持久化一次 `operation.blocked` 事件和 `MANUAL_REVIEW_REQUIRED` 历史记录；服务重启、重复检查或原因改变均不会重复升级同一条未解决操作。既有检查继续运行，不自动取消设备保护。
+
+管理员可在 Webhooks 中订阅 `operation.blocked`；未配置订阅不会自动向外发送通知。事件和 API 记录始终保留，但它们不能替代已配置的通知渠道。单个任务失败、单条未知操作的元数据异常均不应中断其他任务处理。
+
+## 人工处理
+
+1. 根据 operation_id 查看原始错误、恢复原因、当前设备和图库；不点击重新执行来猜测结果。
+2. 调用现有 reconcile 接口并传 `acknowledge=false` 进行核对。
+3. 无法证明成功、但管理员确认可以结束旧操作时，传 `acknowledge=true`：结束为失败，保留原始目标、上传意图和此前错误，记录观察到的图片与人工处理历史。该接口不会重发设备写入。
+4. 有目标一致且同步完成的证据才记为成功。处理后恢复原计划，错过的任务不补发。
+
+仍可能因厂商无法给出明确写入结果而需要人工处理；本策略解决错误误判、可安全重试的暂时失败和长期阻塞缺乏解释的问题，不承诺网络故障时所有设备任务都能自动成功。

docs/NAS.md

@@ -1,7 +1,9 @@
 # Synology NAS deployment / 群晖部署
 
 Target: DS923+, DSM 7.4.1 (verified on target; originally specified 7.3.1), AMD64, Container Manager.
-Directory: /volume2/docker/pigway-frame-flow. Port: 18787.
+Directory: /volume2/docker/pigway-frame-flow. Default published port: 6005.
+The container still listens on 18787; Compose maps host 6005 to container 18787.
+Existing installations must update their own WEB_PORT and recreate the service to activate the change.
 
 ## 1. Package and upload / 打包上传
 
@@ -37,10 +39,14 @@ chmod 600 .env
 Edit `.env` on the NAS. Set FRAME_FLOW_TOKEN to a strong random token. API key
 stays empty. KOKONNA_MOCK=true and KOKONNA_WRITE_ENABLED=false.
 Set WEB_BIND to the actual NAS LAN address (recommended) or explicitly 0.0.0.0;
-WEB_PORT=18787. The latter binds every NAS interface, so use the LAN IP when
+WEB_PORT=6005. The latter binds every NAS interface, so use the LAN IP when
 strict LAN-only binding is required. No firewall/router/proxy edits are performed.
 Copy deploy/devices.yml.example to config/devices.yml if multiple devices are desired.
 
+Set `FRAME_FLOW_STORAGE_NAME` to the NAS display name. The gallery tab shows
+this name followed by “本地图库” (or “Local gallery”). For Actions deployment,
+set the repository Variable of the same name. It is a display label, not a path.
+
 ## 3. Validate, build, start / 验证构建启动
 
 Synology Docker is /usr/local/bin/docker. The SSH user may require sudo. Do not
@@ -61,7 +67,7 @@ sudo /usr/local/bin/docker image inspect pigway-frame-flow:latest \
 Do not print unfiltered `docker inspect`: its environment can contain keys/tokens.
 Likewise do not print `docker compose config` without --quiet on a live installation.
 Run the read-only smoke checker from a machine with Python and set FRAME_FLOW_URL
-to http://NAS_LAN_IP:18787; FRAME_FLOW_TOKEN stays in private env/file.
+to http://NAS_LAN_IP:6005; FRAME_FLOW_TOKEN stays in private env/file.
 
 Health: GET /health → 200. Readiness: GET /ready → 200 when SQLite, driver config,
 auth and Scheduler are ready. Missing credentials in live mode → 503. The cloud

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/PHOTO_SOURCE_CONNECTIONS.md

@@ -23,3 +23,22 @@ The UI labels the top card **Shared connection**, displays source IDs and paths
 on each source card, and explains each source's connection dependency. Shared
 session disconnect is available only in the shared connection card and asks for
 confirmation of its impact on all people-filtered sources.
+
+
+## Gallery destination labels / 图库目的地标签
+
+图库标签描述可保存图片的具体目的地，照片来源连接不自动成为图库目的地。
+当前为 `KoKonna 云端图库` 与 `<FRAME_FLOW_STORAGE_NAME> 本地图库`；
+NAS 名称通过部署配置设置，空值回退为 NAS，不使用容器 ID 代替 NAS 名称。
+英文使用同一实例名称与 cloud gallery / Local gallery。
+
+`GET /api/v1/settings` 的 `gallery_destinations` 提供目的地 ID、适配器、
+实例/服务商名称、存储类型、连接状态和保存能力。只有连接有效、明确支持上传且
+前端存在对应适配器的目的地才进入标签栏。能力默认关闭；全局写入保护仍单独生效，
+目的地的保存能力不等于当前用户获准写入。
+
+后续网盘接入须先实现其读取/保存适配器、校验授权及能力，再注册目的地。
+命名规则为“服务商／实例名称 + 云端图库”，例如已实现保存能力后才可展示
+“百度网盘·家庭 云端图库”。多个账号/实例必须能从名称区分。
+目前 Google Drive、阿里云盘、百度网盘和 WebDAV 仅作为只读照片来源，
+不出现在可保存目的地标签栏，不显示尚未实现的上传入口。

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,
@@ -25,3 +25,23 @@
 The API cannot set coverId. Restoration guarantees a requested image switch when
 confirmed, not arbitrary cover metadata restoration. Physical screen refresh has
 no documented pixel telemetry; visual owner observation supplements cloud synced.
+
+### Upload response reconciliation
+
+Before an upload, the service persists its asset ID, exact SHA256/size, filename,
+existing gallery IDs and timestamp. When the response is lost, read-only queries
+look for one new image in the upload time window; only an exact downloaded-byte
+match identifies it. Ambiguous, missing or altered content remains locked for
+manual review. No upload or switch is replayed by reconciliation.
+
+A proven upload completes the display only when the device reports that exact
+image and `synced=true`. If a normal display remains on its previous synced
+image beyond the sync timeout plus five minutes, two observations at least one
+minute apart record `DISPLAY_NOT_CONFIRMED` and unblock future scheduled work.
+Temporary overrides retain their restore behavior and are not automatically
+closed as failed. Legacy operations without durable upload evidence require
+manual acknowledgement; absence from the gallery alone never proves failure.
+
+### 错误与有限重试
+
+完整错误矩阵、重试边界、持久化恢复状态和人工处理见 [KoKonna 恢复策略](KOKONNA_RECOVERY.md)。自动重试只允许只读请求、连接建立超时或明确限流拒绝；读取超时等未知写入不会重发。

docs/RESEARCH.md

@@ -1,6 +1,7 @@
 # KoKonna API research / 接口调查
 
-Checked 2026-10-01 against https://kokonna.art/pages/openapi.
+Rechecked 2026-10-16 against https://kokonna.art/pages/openapi.
+错误分类、重试和未知写入处理见 [KoKonna 恢复策略](KOKONNA_RECOVERY.md)。
 Base: https://api.kokonna.art/openapi. No fallback to legacy galaxyguide.cn.
 
 | Official endpoint | Frame Flow capability |
@@ -29,7 +30,7 @@ headroom at 18. Device state has a 60-second cache, gallery is loaded on demand.
 Uploads automatically activate a new image; there is no upload-without-activation
 flag. Gallery-only uploads are therefore local staging, not a fictitious cloud
 operation. Maximum upstream request size is 50 MB; this service accepts 20 MiB
-image files with bounded decoded pixels. No non-idempotent cloud write is retried.
+image files with bounded decoded pixels. Only proven-unsent connections or explicit rate-limit rejections may retry a write, within a three-attempt budget. Ambiguous writes are never replayed.
 Cloud acknowledgement is not physical refresh confirmation; /device synced and
 imageId drive the operation state. Unconfirmed or interrupted writes become UNKNOWN
 and block later device writes until read-only reconciliation/explicit acknowledgement.

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

@@ -1,36 +1,62 @@
-# UI layout audit
+# UI 一致性与图片加载检查
 
-The Mock-only `scripts/ui-layout-audit.cjs` checks all 11 navigation pages,
+页面使用既有真实元数据创建控件和图片区域，不使用页面骨架或虚构图片卡片。
-local/cloud gallery layouts and six modal states plus expanded manual collage at 1440, 768 and 390 CSS pixels,
+搜索、排序、卡片操作与写入保护在图片请求前初始化；已知图库数据可先显示，
-in Chinese/English and light/dark themes. It checks page horizontal overflow and
+后台刷新元数据。首页图片独立加载，不阻塞后续页面内容。
-at least 8 pixels between visible input/select/textarea/button rectangles, and
-44-pixel control heights on mobile.
-Closed details, background content behind dialogs and hidden fields are excluded.
-Photos authentication is intercepted with fixture credentials; no NAS login or
-frame write occurs. Populated task/history fixtures remain in disposable Mock data.
 
-This audit found and corrected missing upload preview spacing, nested task field
+图片共用局部加载函数：旋转指示器仅居中显示于所属图片容器，网络请求与解码完成后
-spacing, small mobile action gaps and inconsistent dynamically inserted form
+立即显示图片，失败后显示中英文提示。没有固定等待或动画最短展示时长。
-spacing. NAS source forms now hide irrelevant cloud credential fields. Native
+图库仅请求可见区域及附近图片。浏览器禁缓存不会清除服务端缩略图缓存，
-drive forms expose their credential field and hide local-only quality controls.
+快速图片可能在第一帧绘制前完成，动画不一定肉眼可见。
 
-Synology Photos has a dedicated connection card on the Photo Sources page, with
+手动拼版先创建全部真实区域与坐标/拖动交互，再并行请求图片。
-status, an explanation of affected automation and a direct NAS sign-in dialog.
+每张图片独立完成或失败，持久的区域容器保持加载前后几何位置与坐标索引稳定。
-Folder settings and person selection remain separate. Credentials are not saved;
+过期布局事件不修改新的规划。
-the existing protected session API is used. Successful login does not run a job
-or change frame content. Passwords are cleared from the dialog before submission.
 
-Run against an isolated Mock server with the existing Playwright runtime:
+移动端导航单行横向滚动，当前入口自动进入可见区域；低高度横屏侧栏可滚动。
+页头在窄屏分行，并为底部安全区域留白。可见控件保留 44 像素触控高度，
+当前导航使用 aria-current，扩展表单标签关联相应控件。
+表格与手机导航允许容器内滚动，不应导致整页水平溢出。
+
+## 自动检查
+
+使用隔离 Mock 服务、临时数据与测试账号，禁止对生产执行可写的 Mock 脚本。
+Photos 授权使用拦截测试响应；不需要真实 NAS 凭据。
 
 ```sh
-FRAME_FLOW_URL=http://127.0.0.1:18789 \
+FRAME_FLOW_URL=http://127.0.0.1:6005 \
 FRAME_FLOW_ENV_FILE=/path/to/mock.env \
 FRAME_FLOW_TEST_USERNAME=test-ui \
 FRAME_FLOW_TEST_PASSWORD=test-only-password \
 node scripts/ui-layout-audit.cjs
 ```
 
-Set `NODE_PATH` to the installed Playwright runtime if needed. Optional
+需要已安装的 Playwright；可通过 NODE_PATH 指定运行时。
-`FRAME_FLOW_SCREENSHOT_DIR` saves fixture-only screenshots for visual review.
+FRAME_FLOW_VIEWPORTS 接受包含 width/height 的 JSON 数组；
-The full audit passed 229 checks with no console errors. This complements
+FRAME_FLOW_SCREENSHOT_DIR 可选，用于保存仅含测试数据的截图。
-`ui-smoke.cjs` and `ui-integrations.cjs`; it does not replace functional tests.
+
+| 脚本 | 检查范围 | 本次结果 |
+| --- | --- | --- |
+| ui-layout-audit.cjs | 11 页面、本地/云端图库、6 类弹窗、展开手动拼版；溢出、控件间距、触控高度、弹窗边界 | 16 组尺寸/语言/主题组合，305 项通过 |
+| ui-image-loading.cjs | 三种宽度、明暗主题；局部居中、成功解码、错误提示与无障碍状态 | 45 项通过 |
+| ui-progressive-loading.cjs | 阻塞初始化/元数据/图片/任务筛选；首次无缓存时控件先就绪、输入保留、慢请求切换、列表失败、无骨架 | 18 项通过 |
+| ui-studio-image-loading.cjs | 桌面/手机、明暗主题；并行请求、独立完成/失败、坐标与拖动、稳定区域 | 31 项通过 |
+
+上述检查无页面脚本异常。生产静态文件与构建文件哈希比对、health/ready 检查通过；
+生产浏览器交互验证使用拦截的账号、规划及素材响应，对真实服务仅 GET，
+不代表真实账号密码登录、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/deployment/GITEA_CD.md

@@ -37,6 +37,7 @@ Repository Settings → Actions configuration (private paths/addresses use Secre
 | `PROD_PHOTOS_DIR` (Secret) | Existing read-only photos source if present; otherwise empty |
 | `PROD_WEB_BIND` (Secret) | Exact existing Docker HostIp (`0.0.0.0` or NAS LAN IP etc.) |
 | `PROD_WEB_PORT` | Exact existing mapped port |
+| `FRAME_FLOW_STORAGE_NAME` | Optional NAS display name for the local gallery; defaults to NAS |
 | `PROD_STATE_VOLUME` | Dedicated new deployment journal volume, e.g. `pigway-frame-flow-cd-state` |
 | `PROD_MOCK` | Explicit `true`/`false`, consistent with intended production mode |
 | `PROD_WRITE_ENABLED` | Explicit `true`/`false`; preserve owner's existing write policy |
@@ -107,7 +108,7 @@ been performed during implementation; those are first-run acceptance steps.
    an immutable rollback tag so normal dangling-image cleanup cannot remove it.
 4. Refuse a stale checked-out `main` revision that no longer equals remote main.
    Build an immutable `release-<commit>-<owner>` tag locally, without a registry
-   and without changing `latest` or CI image tags.
+   then point `latest` at the candidate; CI image tags are never changed.
 5. Persist a `prepared` journal with old/new runtime configs. Create an additive
    SQLite online backup under `/data/deploy-backups/<owner>.db`. No data/config
    directory or file is removed, replaced or recursively chowned.
@@ -184,7 +185,7 @@ PROD_IMAGE_REPO=pigway-frame-flow
 PROD_DATA_DIR=/volume1/docker/pigway-frame-flow/data
 PROD_CONFIG_DIR=/volume1/docker/pigway-frame-flow/config
 PROD_WEB_BIND=192.0.2.10
-PROD_WEB_PORT=18787
+PROD_WEB_PORT=6005
 PROD_STATE_VOLUME=pigway-frame-flow-cd-state
 PROD_MOCK=true
 PROD_WRITE_ENABLED=false
@@ -263,10 +264,10 @@ as an Actions artifact. First bootstrap has no prior healthy version to roll bac
 3. Require `BOOTSTRAP VERIFIED` in the deploy log. In Container Manager confirm
    container `pigway-frame-flow` is running/healthy, user 10333, restart unless-stopped,
    exact `/volume1/docker/pigway-frame-flow/{data,config}` mounts and
-   `192.0.2.10:18787` binding (not loopback).
+   `192.0.2.10:6005` binding (not loopback).
-4. Open `http://192.0.2.10:18787/api/v1/version`; its `commit` must equal the full
+4. Open `http://192.0.2.10:6005/api/v1/version`; its `commit` must equal the full
    workflow checkout commit. Check `/ready` returns HTTP 200. The immutable image tag
-   is `pigway-frame-flow:release-<commit>-<transaction>`; compare its image ID in
+   is `pigway-frame-flow:latest`; compare its image ID in
    Container Manager with the running container.
 5. Keep `PROD_DEPLOY_ENABLED=true`. Subsequent main pushes Verify then deploy using
    this same runtime and journal mechanism. The first update records bootstrap as
@@ -363,3 +364,18 @@ the audit client's normal HTTP freshness rules. It is not a permanent offline
 snapshot or a cross-job cache. Raw network exceptions are omitted because proxy
 URLs may contain credentials. Logs identify the advisory host and whether the
 complete audit succeeded.
+
+### Production image retention
+
+Production uses `pigway-frame-flow:latest`. Builds first create a unique release
+image, then tag it as latest before activation. The old image is pinned during
+an update so a failed deployment can restore it. Only after the new version
+passes verification are old release/rollback images and duplicate tags removed.
+After successful deployment, only the current production image remains; there
+is no retained historical image for manual rollback. Rebuild a historical
+revision before manually reverting a successful deployment.
+
+Images referenced by other containers (including stopped containers), images
+with unrelated tags, and CI resources remain protected. Cleanup never prunes
+volumes, data, or shared build cache. Cleanup failure is a warning and does not
+roll back a verified deployment. Failed deployments do not run cleanup.

docs/openapi.json

@@ -1,8 +1,8 @@
 {
   "openapi": "3.1.0",
   "info": {
-    "title": "Pigway Frame Flow API",
+    "title": "PIGWay Frame Flow API",
-    "version": "0.1.0"
+    "version": "0.1.9"
   },
   "paths": {
     "/api/v1/devices/{device_id}/widgets/selection": {
@@ -6397,7 +6397,15 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/TemplateContent"
+                "anyOf": [
+                  {
+                    "$ref": "#/components/schemas/TemplateContent"
+                  },
+                  {
+                    "$ref": "#/components/schemas/AutoCollageContent"
+                  }
+                ],
+                "title": "Payload"
               }
             }
           }
@@ -14298,6 +14306,87 @@
         ],
         "title": "AssetBatch"
       },
+      "AutoCollageContent": {
+        "properties": {
+          "type": {
+            "type": "string",
+            "const": "auto_collage",
+            "title": "Type"
+          },
+          "source_id": {
+            "anyOf": [
+              {
+                "type": "string",
+                "pattern": "^[a-z0-9-]{1,60}$"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Source Id"
+          },
+          "count": {
+            "type": "integer",
+            "maximum": 12.0,
+            "minimum": 1.0,
+            "title": "Count",
+            "default": 4
+          },
+          "title": {
+            "type": "string",
+            "maxLength": 100,
+            "title": "Title",
+            "default": ""
+          },
+          "message": {
+            "type": "string",
+            "maxLength": 500,
+            "title": "Message",
+            "default": ""
+          },
+          "orientation": {
+            "type": "string",
+            "enum": [
+              "auto",
+              "portrait",
+              "landscape"
+            ],
+            "title": "Orientation",
+            "default": "auto"
+          },
+          "style": {
+            "type": "string",
+            "enum": [
+              "grid",
+              "hero",
+              "poster"
+            ],
+            "title": "Style",
+            "default": "grid"
+          },
+          "use_ai": {
+            "type": "boolean",
+            "title": "Use Ai",
+            "default": true
+          },
+          "prompt": {
+            "type": "string",
+            "maxLength": 1500,
+            "title": "Prompt",
+            "default": ""
+          },
+          "profile": {
+            "$ref": "#/components/schemas/Profile",
+            "default": "color"
+          }
+        },
+        "additionalProperties": false,
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "title": "AutoCollageContent"
+      },
       "Body_import_images_api_v1_layout_images_post": {
         "properties": {
           "files": {
@@ -14730,6 +14819,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": {
@@ -14778,6 +14885,9 @@
               {
                 "$ref": "#/components/schemas/PhotoSourceContent"
               },
+              {
+                "$ref": "#/components/schemas/AutoCollageContent"
+              },
               {
                 "$ref": "#/components/schemas/ProviderContent"
               },
@@ -14789,6 +14899,7 @@
             "discriminator": {
               "propertyName": "type",
               "mapping": {
+                "auto_collage": "#/components/schemas/AutoCollageContent",
                 "html": "#/components/schemas/FutureContent",
                 "image": "#/components/schemas/ImageContent",
                 "image_url": "#/components/schemas/URLContent",
@@ -14852,6 +14963,7 @@
           "UNSUPPORTED_CAPABILITY",
           "RENDER_FAILED",
           "UPLOAD_FAILED",
+          "DISPLAY_NOT_CONFIRMED",
           "WRITE_RESULT_UNKNOWN",
           "RATE_LIMITED",
           "INTERNAL_ERROR",
@@ -14953,6 +15065,48 @@
         ],
         "title": "FutureContent"
       },
+      "GalleryDestination": {
+        "properties": {
+          "id": {
+            "type": "string",
+            "title": "Id"
+          },
+          "adapter": {
+            "type": "string",
+            "title": "Adapter"
+          },
+          "name": {
+            "type": "string",
+            "title": "Name"
+          },
+          "storage": {
+            "type": "string",
+            "enum": [
+              "cloud",
+              "local"
+            ],
+            "title": "Storage"
+          },
+          "connected": {
+            "type": "boolean",
+            "title": "Connected",
+            "default": false
+          },
+          "supports_upload": {
+            "type": "boolean",
+            "title": "Supports Upload",
+            "default": false
+          }
+        },
+        "type": "object",
+        "required": [
+          "id",
+          "adapter",
+          "name",
+          "storage"
+        ],
+        "title": "GalleryDestination"
+      },
       "GalleryImage": {
         "properties": {
           "starred": {
@@ -15062,7 +15216,7 @@
           "version": {
             "type": "string",
             "title": "Version",
-            "default": "0.1.0"
+            "default": "0.1.9"
           }
         },
         "type": "object",
@@ -15324,6 +15478,9 @@
                   {
                     "$ref": "#/components/schemas/PhotoSourceContent"
                   },
+                  {
+                    "$ref": "#/components/schemas/AutoCollageContent"
+                  },
                   {
                     "$ref": "#/components/schemas/ProviderContent"
                   },
@@ -15334,6 +15491,7 @@
                 "discriminator": {
                   "propertyName": "type",
                   "mapping": {
+                    "auto_collage": "#/components/schemas/AutoCollageContent",
                     "html": "#/components/schemas/FutureContent",
                     "image": "#/components/schemas/ImageContent",
                     "image_url": "#/components/schemas/URLContent",
@@ -15469,6 +15627,9 @@
                   {
                     "$ref": "#/components/schemas/PhotoSourceContent"
                   },
+                  {
+                    "$ref": "#/components/schemas/AutoCollageContent"
+                  },
                   {
                     "$ref": "#/components/schemas/ProviderContent"
                   },
@@ -15479,6 +15640,7 @@
                 "discriminator": {
                   "propertyName": "type",
                   "mapping": {
+                    "auto_collage": "#/components/schemas/AutoCollageContent",
                     "html": "#/components/schemas/FutureContent",
                     "image": "#/components/schemas/ImageContent",
                     "image_url": "#/components/schemas/URLContent",
@@ -15787,6 +15949,16 @@
       },
       "Operation": {
         "properties": {
+          "recovery": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/RecoveryState"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
           "operation_id": {
             "type": "string",
             "title": "Operation Id"
@@ -16160,6 +16332,7 @@
             "type": "string",
             "enum": [
               "local",
+              "synology-photos",
               "webdav",
               "google-drive",
               "alipan",
@@ -16312,6 +16485,7 @@
             "type": "string",
             "enum": [
               "local",
+              "synology-photos",
               "webdav",
               "google-drive",
               "alipan",
@@ -16808,6 +16982,49 @@
         ],
         "title": "Reconciliation"
       },
+      "RecoveryState": {
+        "properties": {
+          "state": {
+            "type": "string",
+            "enum": [
+              "checking",
+              "manual_review",
+              "resolved"
+            ],
+            "title": "State"
+          },
+          "reason": {
+            "type": "string",
+            "title": "Reason"
+          },
+          "first_checked_at": {
+            "type": "string",
+            "title": "First Checked At"
+          },
+          "last_checked_at": {
+            "type": "string",
+            "title": "Last Checked At"
+          },
+          "checks": {
+            "type": "integer",
+            "title": "Checks"
+          },
+          "requires_manual_review": {
+            "type": "boolean",
+            "title": "Requires Manual Review"
+          }
+        },
+        "type": "object",
+        "required": [
+          "state",
+          "reason",
+          "first_checked_at",
+          "last_checked_at",
+          "checks",
+          "requires_manual_review"
+        ],
+        "title": "RecoveryState"
+      },
       "Region": {
         "properties": {
           "asset_id": {
@@ -16936,6 +17153,25 @@
       },
       "SettingsView": {
         "properties": {
+          "storage_name": {
+            "type": "string",
+            "title": "Storage Name",
+            "default": "NAS"
+          },
+          "gallery_destinations": {
+            "items": {
+              "$ref": "#/components/schemas/GalleryDestination"
+            },
+            "type": "array",
+            "title": "Gallery Destinations"
+          },
+          "device_catalog": {
+            "items": {
+              "$ref": "#/components/schemas/DeviceIdentity"
+            },
+            "type": "array",
+            "title": "Device Catalog"
+          },
           "version": {
             "type": "string",
             "title": "Version"
@@ -17173,12 +17409,12 @@
           "product": {
             "type": "string",
             "title": "Product",
-            "default": "Pigway Frame Flow"
+            "default": "PIGWay Frame Flow"
           },
           "version": {
             "type": "string",
             "title": "Version",
-            "default": "0.1.0"
+            "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.5.md

@@ -0,0 +1,31 @@
+# PIGWay Frame Flow v0.1.5
+
+## 简体中文
+
+- 图片仅在真实图片区域内居中显示加载动画，无页面骨架、虚构图片卡片或人为展示延时；请求及解码完成后立即显示，失败时显示局部提示。
+- 图库搜索、排序、卡片操作及写入保护先于图片请求初始化，复用真实列表元数据；本地任务筛选异步填充，不阻塞其他控件。
+- 手动拼版改为并行加载，各图独立完成或失败；固定区域容器保留坐标和拖动交互，加载前后位置一致。
+- 修复手机底栏文字裁切、窄屏页头拥挤和横屏导航可达性，支持底部安全区域，补齐表单标签和当前导航无障碍状态。
+- 默认对外访问端口改为 **6005**。本地启动、Compose、测试地址及文档同步；容器内部仍监听 18787。
+
+### 验证
+
+本地 505 项 Python 测试、Ruff、格式检查、mypy、JavaScript 语法和差异检查通过。
+浏览器回归：布局 305 项、图片加载 45 项、图库加载顺序 14 项、手动拼版 31 项通过。
+先行 UI 部署的生产静态文件哈希、health/ready 和拦截测试数据下的浏览器交互已验证；
+不代表真实 AI 生成、画框写入、手机实机或软键盘测试。
+
+### 升级说明
+
+已有安装须更新私有环境配置中的 `WEB_PORT=6005`，并重建服务后生效。
+自动部署的 `PROD_WEB_PORT` 必须与现有实例的映射一致；仅修改该变量不能迁移端口。
+NAS 附件是源码部署包，需自行构建 Docker 镜像，不含密钥、运行配置、数据库或私人照片。
+
+## English
+
+Image loading indicators stay inside real image regions, without page skeletons or artificial delays.
+Gallery controls initialize before image requests. Manual collage images load independently in parallel,
+with stable regions and working coordinate/drag controls. Mobile navigation, safe-area spacing and form
+accessibility are improved. The default published port is now **6005**, mapped to container port 18787.
+Existing installations must update their private port configuration and recreate the service.
+NAS source package and SHA256 checksum are included; this is not a prebuilt Docker image.

docs/releases/v0.1.6.md

@@ -0,0 +1,29 @@
+# PIGWay Frame Flow v0.1.6
+
+## 简体中文
+
+- 图库使用具体目的地标签：`KoKonna 云端图库` 与 `<NAS 名称> 本地图库`，NAS 名称通过 `FRAME_FLOW_STORAGE_NAME` 配置。
+- Settings API 增加目的地元数据，标签仅展示连接已配置、明确支持保存且存在适配器的目的地；全局写入保护保持独立。
+- 后续网盘须实现读取/保存适配器并完成连接后才能加入标签栏，显示具体服务商/实例名称。当前只读照片来源不会作为保存目的地展示。
+- 长标签在手机上换行，避免整页横向溢出；中英文保持相同目的地身份。
+- Compose 和自动部署透传 NAS 展示名称；分支 CI 完整验证后发布标签，避免相同提交的标签推送重复占用构建队列。
+
+### 验证
+
+本地 507 项 Python 测试、Ruff、格式检查、mypy、JavaScript 语法检查通过。
+图库目的地标签与能力过滤 18 项浏览器检查通过；覆盖 320–1440 像素、中英文、明暗主题和长 NAS 名称。
+本次不增加任何网盘写入功能，不改变画框写入策略。
+
+### 升级
+
+Compose 设置 `FRAME_FLOW_STORAGE_NAME`；Actions 设置同名仓库 Variable。
+名称只描述实例，不作为路径或授权凭据。未设置时回退为 NAS。
+默认访问端口仍为 6005，容器内部端口仍为 18787。
+NAS 源码包与 SHA256 附件不含运行配置、密钥、数据库或私人照片，需自行构建镜像。
+
+## English
+
+Gallery tabs identify the concrete destination: KoKonna cloud gallery and the configured NAS name plus Local gallery.
+Destination metadata includes connection and upload capabilities; only implemented writable adapters are shown.
+Existing read-only cloud photo sources are not presented as save destinations. Long labels wrap on mobile.
+Set FRAME_FLOW_STORAGE_NAME in Compose or the Actions repository Variables. No cloud-drive write support or device write policy is changed.

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,9 +33,11 @@ from pigway_frame_flow.models import (
     CurrentDisplay,
     DeleteRequest,
     Device,
+    DeviceIdentity,
     DisplayRequest,
     ErrorResponse,
     Fit,
+    GalleryDestination,
     GalleryImage,
     Health,
     History,
@@ -122,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.0",
+        version="0.1.16",
         lifespan=lifespan,
         responses=error_responses,
     )
@@ -303,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
@@ -941,6 +944,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(
@@ -1000,7 +1004,36 @@ def create_app(settings=None, start_worker=True):
     )
     def settings_view():
         return SettingsView(
-            version="0.1.0",
+            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",
+                    adapter="kokonna",
+                    name="KoKonna",
+                    storage="cloud",
+                    supports_upload=True,
+                    connected=settings.mock
+                    or bool(settings.api_key)
+                    or any(registry.keys),
+                ),
+                GalleryDestination(
+                    id="local",
+                    adapter="local-assets",
+                    name=settings.storage_name,
+                    storage="local",
+                    connected=True,
+                    supports_upload=True,
+                ),
+            ],
+            version="0.1.16",
             mock=settings.mock,
             write_enabled=settings.write_enabled,
             api_key_configured=bool(settings.api_key)
@@ -1229,7 +1262,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 source.get("type") in ("photo_source", "auto_collage")
-            and content.get("item_id") is None
+            and source.get("item_id") is None
             else None
         )
         self.db.execute(

pigway_frame_flow/display/recovery.py

@@ -0,0 +1,73 @@
+"""Durable, read-only recovery progress for writes with uncertain outcomes."""
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from pigway_frame_flow.storage.database import encode, now_iso
+
+
+class RecoveryMonitor:
+    def __init__(self, service):
+        self.service, self.db = service, service.db
+
+    def observe(self, op, reason):
+        timestamp = now_iso()
+        age = (
+            datetime.now(UTC) - datetime.fromisoformat(op["created_at"])
+        ).total_seconds()
+        review = age >= self.service.settings.sync_timeout + 300
+        with self.db.transaction() as tx:
+            previous = tx.execute(
+                "SELECT * FROM operation_recovery WHERE operation_id=?", (op["id"],)
+            ).fetchone()
+            # Once escalated, wall-clock corrections must not clear the alert.
+            review = review or bool(previous and previous["state"] == "manual_review")
+            state = "manual_review" if review else "checking"
+            tx.execute(
+                "INSERT INTO operation_recovery VALUES(?,?,?,?,?,1) ON CONFLICT(operation_id) DO UPDATE SET state=excluded.state,reason=excluded.reason,last_checked_at=excluded.last_checked_at,checks=operation_recovery.checks+1",
+                (op["id"], state, reason, timestamp, timestamp),
+            )
+            if review and (not previous or previous["state"] != "manual_review"):
+                tx.execute(
+                    "INSERT INTO events VALUES(?,?,?,?)",
+                    (
+                        uuid4().hex,
+                        "operation.blocked",
+                        encode(
+                            {
+                                "operation_id": op["id"],
+                                "device_id": op["device_id"],
+                                "reason": reason,
+                                "requires_manual_review": True,
+                            }
+                        ),
+                        timestamp,
+                    ),
+                )
+                tx.execute(
+                    "INSERT INTO history(client_id,request_id,operation_id,device_id,action,result,timestamp) VALUES(?,?,?,?,?,?,?)",
+                    (
+                        op["client_id"],
+                        op["request_id"],
+                        op["id"],
+                        op["device_id"],
+                        op["action"],
+                        "MANUAL_REVIEW_REQUIRED",
+                        timestamp,
+                    ),
+                )
+
+    def resolve(self, operation_id):
+        self.db.execute(
+            "UPDATE operation_recovery SET state='resolved' WHERE operation_id=? AND state!='resolved'",
+            (operation_id,),
+        )
+
+    def info(self, operation_id):
+        row = self.db.one(
+            "SELECT state,reason,first_checked_at,last_checked_at,checks FROM operation_recovery WHERE operation_id=?",
+            (operation_id,),
+        )
+        if row:
+            row["requires_manual_review"] = row["state"] == "manual_review"
+        return row

pigway_frame_flow/display/service.py

@@ -6,7 +6,9 @@ from datetime import UTC, datetime, timedelta
 from uuid import uuid4
 
 from pigway_frame_flow.display.cloud_library import CloudLibrary
+from pigway_frame_flow.display.recovery import RecoveryMonitor
 from pigway_frame_flow.display.retention import Retention
+from pigway_frame_flow.display.upload_reconciliation import UploadReconciliation
 from pigway_frame_flow.drivers.base import DriverRegistry
 from pigway_frame_flow.errors import ErrorCode as E
 from pigway_frame_flow.errors import FlowError
@@ -49,7 +51,10 @@ class DisplayService:
         self.lock = threading.RLock()
         self.retention = Retention(self)
         self.cloud_library = CloudLibrary(self)
+        self.recovery = RecoveryMonitor(self)
+        self.upload_reconciliation = UploadReconciliation(self)
         self.expiration_checked: dict[str, float] = {}
+        self.unknown_checked: dict[str, float] = {}
         # A killed write cannot be replayed safely; pre-write work can resume.
         db.execute(
             "UPDATE operations SET status='UNKNOWN', updated_at=? WHERE write_started=1 AND status IN ('UPLOADING','RENDERING')",
@@ -110,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,),
@@ -162,14 +167,16 @@ class DisplayService:
             request_id=op["request_id"],
             client_id=op["client_id"],
             action=op["action"],
+            recovery=self.recovery.info(id),
         )
 
     def update(self, id, status, result=None, error=None):
         if result:
             row = self.db.one("SELECT result FROM operations WHERE id=?", (id,))
             previous = json.loads(row["result"]) if row and row["result"] else {}
-            if "photo_attempts" in previous:
+            for key in ("photo_attempts", "upload_intent"):
-                result = {**result, "photo_attempts": previous["photo_attempts"]}
+                if key in previous:
+                    result = {**result, key: previous[key]}
         self.db.execute(
             "UPDATE operations SET status=?,updated_at=?,result=COALESCE(?,result),error=? WHERE id=?",
             (
@@ -180,6 +187,15 @@ 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)
 
     def blocked(self, device_id):
         return (
@@ -196,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)}
@@ -214,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,
@@ -347,7 +392,7 @@ class DisplayService:
                         "UPDATE operations SET result=? WHERE id=?",
                         (encode({"photo_attempts": attempts}), operation_id),
                     )
-                return self.assets.put(rendered, name)
+                return self.assets.put(rendered, name, "cache" if staging else "images")
             raise FlowError(
                 E.INVALID_REQUEST, "No decodable photo found within 5 candidates"
             )
@@ -360,11 +405,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=?",
@@ -415,10 +463,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",
@@ -438,7 +514,7 @@ class DisplayService:
                         "code": exc.code,
                         "message": exc.message,
                         "request_id": op["request_id"],
-                        "details": {},
+                        "details": exc.details,
                     }
                     self.update(
                         op["id"], "UNKNOWN" if uncertain else "FAILED", error=error
@@ -502,6 +578,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 (
@@ -540,7 +618,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)
@@ -594,6 +677,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")
@@ -610,7 +700,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(
@@ -626,6 +716,8 @@ class DisplayService:
             raise FlowError(
                 E.CONFLICT, "Temporary override requires an existing image", 409
             )
+        if asset:
+            self.upload_reconciliation.prepare(id, driver, asset, previous)
         self._start_write(id)
         if asset:
             self.update(id, "UPLOADING")
@@ -643,7 +735,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=?",
@@ -689,6 +780,64 @@ class DisplayService:
         )
 
     def sync(self):
+        with self.lock:
+            self._sync()
+
+    def _sync(self):
+        # Late acknowledgements only resolve a known display target. Never replay
+        # writes or infer success from gallery presence alone.
+        for op in self.db.all(
+            "SELECT * FROM operations WHERE status='UNKNOWN' AND action!='render-ai' AND write_started=1"
+        ):
+            expected = json.loads(op["result"] or "{}").get("image_id")
+            intent = json.loads(op["result"] or "{}").get("upload_intent")
+            checked = time.monotonic()
+            if checked - self.unknown_checked.get(op["id"], float("-inf")) < 60:
+                continue
+            self.unknown_checked[op["id"]] = checked
+            if op["action"] != "display" or (not expected and not intent):
+                self.recovery.observe(
+                    op,
+                    "missing_upload_evidence"
+                    if op["action"] == "display"
+                    else "manual_reconciliation_required",
+                )
+                continue
+            try:
+                driver = self.registry.get(op["device_id"])
+                device = driver.device(refresh=True)
+                if intent:
+                    expected = self.upload_reconciliation.check(op, driver, device)
+                    if (
+                        self.db.one(
+                            "SELECT status FROM operations WHERE id=?", (op["id"],)
+                        )["status"]
+                        == "FAILED"
+                    ):
+                        continue
+                if (
+                    expected
+                    and device.current_content.id == expected
+                    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"]})
+                    self.unknown_checked.pop(op["id"], None)
+                elif expected:
+                    self.recovery.observe(
+                        op,
+                        "waiting_device_sync"
+                        if device.current_content.id == expected
+                        else "target_mismatch",
+                    )
+            except FlowError:
+                self.recovery.observe(op, "read_unavailable")
+            except Exception:
+                # Bad vendor metadata for one operation must not stop the worker.
+                self.recovery.observe(op, "reconciliation_error")
         for op in self.db.all("SELECT * FROM operations WHERE status='SYNCING'"):
             try:
                 device = self.registry.get(op["device_id"]).device()
@@ -698,6 +847,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"]})
@@ -821,9 +971,25 @@ class DisplayService:
                 self.update(
                     id,
                     "COMPLETED" if confirmed else "FAILED",
-                    {"image_id": device.current_content.id},
+                    op["result"],
+                    error=None
+                    if confirmed
+                    else {
+                        "code": E.DISPLAY_NOT_CONFIRMED
+                        if op["action"] == "display"
+                        else E.WRITE_RESULT_UNKNOWN,
+                        "message": "Manually closed unconfirmed write; no write replayed",
+                        "request_id": op["request_id"],
+                        "details": {
+                            "observed_image_id": device.current_content.id,
+                            "previous_error": op["error"],
+                        },
+                    },
                 )
                 resolved = True
+                if confirmed and op["action"] == "display":
+                    self.cloud_library.confirm(id)
+                    self.db.event("operation.completed", {"operation_id": id})
                 self.db.history(
                     dict(
                         id=id,

pigway_frame_flow/display/upload_reconciliation.py

@@ -0,0 +1,163 @@
+"""Resolve missing upload responses using read-only, exact-content evidence."""
+
+import hashlib
+import json
+from datetime import UTC, datetime, timedelta
+
+from pigway_frame_flow.errors import ErrorCode
+from pigway_frame_flow.storage.database import encode, now_iso
+
+
+class UploadReconciliation:
+    def __init__(self, service):
+        self.service = service
+
+    def prepare(self, operation_id, driver, asset, previous):
+        path = self.service.assets.path(asset["asset_id"])
+        self.service.update(
+            operation_id,
+            "RENDERING",
+            {
+                "rendered_asset_id": asset["asset_id"],
+                "upload_intent": {
+                    "name": asset["name"],
+                    "sha256": hashlib.sha256(path.read_bytes()).hexdigest(),
+                    "size": path.stat().st_size,
+                    "before_ids": [image.image_id for image in driver.images()],
+                    "previous_image_id": previous,
+                    "started_at": now_iso(),
+                },
+            },
+        )
+
+    def check(self, op, driver, device):
+        service = self.service
+        result = json.loads(op["result"] or "{}")
+        intent = result.get("upload_intent")
+        if not intent:
+            return None
+        expected = result.get("image_id")
+        if not expected:
+            start = datetime.fromisoformat(intent["started_at"])
+            candidates = []
+            for image in driver.images():
+                if (
+                    image.image_id in intent["before_ids"]
+                    or image.name != intent["name"]
+                ):
+                    continue
+                if image.size_bytes is not None and image.size_bytes != intent["size"]:
+                    continue
+                if not image.created_at:
+                    continue
+                try:
+                    created = datetime.fromisoformat(image.created_at)
+                    age = (created - start).total_seconds()
+                except (ValueError, TypeError):
+                    continue
+                if 0 <= age <= service.settings.sync_timeout + 300:
+                    candidates.append(image)
+            # Ambiguous matches never release a write lock.
+            if len(candidates) != 1:
+                service.recovery.observe(
+                    op,
+                    "gallery_match_missing"
+                    if not candidates
+                    else "gallery_match_ambiguous",
+                )
+                return None
+            expected = candidates[0].image_id
+            data = driver.download(expected)
+            if (
+                len(data) != intent["size"]
+                or hashlib.sha256(data).hexdigest() != intent["sha256"]
+            ):
+                service.recovery.observe(op, "content_mismatch")
+                return None
+            result["image_id"] = expected
+            result["upload_confirmed"] = True
+            service.update(op["id"], "UNKNOWN", result, json.loads(op["error"] or "{}"))
+            source = service.db.one(
+                "SELECT payload FROM asset_sources WHERE asset_id=?",
+                (result["rendered_asset_id"],),
+            )
+            service.db.execute(
+                "INSERT OR REPLACE INTO image_sources VALUES(?,?,?,?,?)",
+                (
+                    op["device_id"],
+                    expected,
+                    result["rendered_asset_id"],
+                    op["id"],
+                    source["payload"] if source else encode({"type": "image"}),
+                ),
+            )
+            if not service.db.one(
+                "SELECT image_id FROM managed_cloud_uploads WHERE operation_id=?",
+                (op["id"],),
+            ):
+                service.cloud_library.register(
+                    op["device_id"], expected, result["rendered_asset_id"], op["id"]
+                )
+        if device.current_content.id == expected and device.current_content.synced:
+            options = json.loads(op["payload"]).get("options", {})
+            service.db.execute(
+                "UPDATE device_state SET managed_image_id=? WHERE device_id=?",
+                (expected, op["device_id"]),
+            )
+            if options.get("restore_previous"):
+                expires = datetime.fromisoformat(intent["started_at"]) + timedelta(
+                    seconds=options["duration"]
+                )
+                service.db.execute(
+                    "INSERT OR IGNORE INTO overrides VALUES(?,?,?,?,?,?)",
+                    (
+                        op["id"],
+                        op["device_id"],
+                        expected,
+                        options["priority"],
+                        expires.isoformat(),
+                        intent["started_at"],
+                    ),
+                )
+            return expected
+        elapsed = (
+            datetime.now(UTC) - datetime.fromisoformat(intent["started_at"])
+        ).total_seconds()
+        if (
+            result.get("upload_confirmed")
+            and not json.loads(op["payload"]).get("options", {}).get("restore_previous")
+            and elapsed > service.settings.sync_timeout + 300
+            and device.current_content.id == intent["previous_image_id"]
+            and device.current_content.synced
+        ):
+            # Upload is proven; display is not. Two separated stable observations
+            # close the failed display, without replaying either vendor write.
+            observed = result.get("unchanged_observed_at")
+            if not observed:
+                result["unchanged_observed_at"] = now_iso()
+                service.update(
+                    op["id"], "UNKNOWN", result, json.loads(op["error"] or "{}")
+                )
+            elif (
+                datetime.now(UTC) - datetime.fromisoformat(observed)
+            ).total_seconds() >= 60:
+                service.update(
+                    op["id"],
+                    "FAILED",
+                    result,
+                    {
+                        "code": ErrorCode.DISPLAY_NOT_CONFIRMED,
+                        "message": "Upload confirmed; frame remained on previous image",
+                        "request_id": op["request_id"],
+                        "details": {},
+                    },
+                )
+                service.db.history(op, "DISPLAY_NOT_CONFIRMED")
+                service.db.event(
+                    "operation.failed",
+                    {"operation_id": op["id"], "code": ErrorCode.DISPLAY_NOT_CONFIRMED},
+                )
+        elif result.get("unchanged_observed_at"):
+            result.pop("unchanged_observed_at")
+            service.update(op["id"], "UNKNOWN", result, json.loads(op["error"] or "{}"))
+        return expected

pigway_frame_flow/drivers/kokonna/client.py

@@ -1,7 +1,7 @@
 """Hardened adapter over the MIT-0 guooscar 1.2.0 device/upload methods.
 
 No UI, scheduler, renderer, environment lookup, or constructor cloud calls.
-Never retry a write; a timeout may have occurred after cloud acceptance.
+Retry only read-only requests or writes proven unsent/rejected; never replay ambiguous writes.
 """
 
 import threading
@@ -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
@@ -19,28 +20,85 @@ BASE_URL = "https://api.kokonna.art/openapi"
 
 
 class SafeTransport:
+    MAX_ATTEMPTS = 3
+    MAX_RETRY_DELAY = 60
+
     def __init__(self, key, session=None):
         self.key = key
         self.session = session or requests.Session()
         self.calls: deque[float] = deque()
         self.lock = threading.Lock()
+        self.cooldown_until = 0.0
 
     def request(self, endpoint, payload=None, write=False, binary=False):
-        if not self.key:
+        for attempt in range(1, self.MAX_ATTEMPTS + 1):
-            raise FlowError(E.CONFIG_REQUIRED, "KoKonna configuration required", 503)
+            try:
+                return self._request_once(endpoint, payload, write, binary)
+            except FlowError as exc:
+                exc.details["attempts"] = attempt
+                delay = max(
+                    2 ** (attempt - 1), exc.details.get("retry_after_seconds", 0)
+                )
+                if (
+                    not exc.details.get("retryable")
+                    or attempt == self.MAX_ATTEMPTS
+                    or delay > self.MAX_RETRY_DELAY
+                ):
+                    if exc.details.get("retryable"):
+                        exc.details["retry_exhausted"] = attempt == self.MAX_ATTEMPTS
+                        exc.details["retry_deferred"] = delay > self.MAX_RETRY_DELAY
+                    raise
+                time.sleep(delay)
+        raise AssertionError("Retry loop exhausted")
+
+    def _reserve(self):
         with self.lock:
             current = time.monotonic()
             while self.calls and current - self.calls[0] >= 60:
                 self.calls.popleft()
-            # Reserve capacity beneath the official 20/minute ceiling.
+            delay = max(0.0, self.cooldown_until - current)
             if len(self.calls) >= 18:
-                raise FlowError(E.RATE_LIMITED, "Device request budget exhausted", 429)
+                delay = max(delay, 60 - (current - self.calls[0]))
+            if delay:
+                raise FlowError(
+                    E.RATE_LIMITED,
+                    "Device request budget exhausted",
+                    429,
+                    details={
+                        "retryable": True,
+                        "retry_after_seconds": delay,
+                        "write_outcome": "not_sent",
+                        "failure_kind": "local_rate_limit",
+                    },
+                )
             self.calls.append(current)
-        url = BASE_URL + endpoint
+
+    @staticmethod
+    def _retry_after(value):
+        from datetime import UTC, datetime
+        from email.utils import parsedate_to_datetime
+
+        try:
+            seconds = float(value)
+        except (ValueError, TypeError):
+            try:
+                seconds = (
+                    parsedate_to_datetime(value) - datetime.now(UTC)
+                ).total_seconds()
+            except (ValueError, TypeError, OverflowError):
+                return 60.0
+        import math
+
+        return max(0.0, seconds) if math.isfinite(seconds) else 60.0
+
+    def _request_once(self, endpoint, payload, write, binary):
+        if not self.key:
+            raise FlowError(E.CONFIG_REQUIRED, "KoKonna configuration required", 503)
+        self._reserve()
         try:
             response = self.session.request(
                 "GET" if binary else "POST",
-                url,
+                BASE_URL + endpoint,
                 headers={}
                 if binary
                 else {
@@ -51,49 +109,148 @@ class SafeTransport:
                 timeout=(5, 120 if endpoint == "/upload" else 30),
                 allow_redirects=False,
             )
-        except requests.RequestException:
+        except requests.RequestException as exc:
+            # Never retain exception text or a URL: binary URLs contain the key.
+            category = next(
+                (
+                    label
+                    for kind, label in (
+                        (requests.ConnectTimeout, "connect_timeout"),
+                        (requests.ReadTimeout, "read_timeout"),
+                        (requests.exceptions.SSLError, "tls_error"),
+                        (requests.ConnectionError, "connection_error"),
+                        (requests.Timeout, "timeout"),
+                    )
+                    if isinstance(exc, kind)
+                ),
+                "request_error",
+            )
+            # 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 write else E.CLOUD_UNAVAILABLE,
+                E.WRITE_RESULT_UNKNOWN if uncertain else E.CLOUD_UNAVAILABLE,
                 "Cloud write outcome is unknown"
-                if write
+                if uncertain
                 else "Device cloud is unavailable",
                 502,
+                details={
+                    "transport_error": category,
+                    "retryable": (not write and category != "tls_error") or not_sent,
+                    "write_outcome": "unknown"
+                    if uncertain
+                    else ("not_sent" if write else "read_only"),
+                },
             ) from None
-        if response.status_code != 200:
-            code = (
-                E.RATE_LIMITED
-                if response.status_code == 429
-                else (
-                    E.WRITE_RESULT_UNKNOWN
-                    if write and response.status_code >= 500
-                    else E.CLOUD_UNAVAILABLE
-                )
-            )
-            raise FlowError(
-                code,
-                "Device cloud request failed",
-                429 if code == E.RATE_LIMITED else 502,
-            )
-        if binary:
-            if len(response.content) > 20 * 1024 * 1024:
-                raise FlowError(E.INVALID_REQUEST, "Cloud image exceeds size limit")
-            return response.content
         try:
-            value = response.json()
+            value = None
-            if not isinstance(value, dict):
+            if not binary or response.status_code != 200:
-                raise ValueError()
+                try:
-            # Cloud errors may echo credentials: never return raw messages.
+                    value = response.json()
-            if value.get("success") is False or (
+                except ValueError:
-                "message" in value and "id" not in value
+                    pass
+            message = value.get("message") if isinstance(value, dict) else None
+            status = response.status_code
+            # Only exact documented business failures establish rejection. Generic
+            # 5xx responses may arrive after a write; those remain UNKNOWN.
+            business = None
+            if status in (404, 500) and isinstance(message, str):
+                if message == "image not found":
+                    business = (
+                        E.NOT_FOUND,
+                        "Cloud image not found",
+                        404,
+                        "image_not_found",
+                    )
+                elif status == 500 and message == "imageId is empty":
+                    business = (
+                        E.INVALID_REQUEST,
+                        "Cloud image ID is invalid",
+                        400,
+                        "invalid_image_id",
+                    )
+                elif status == 500 and message.startswith("can not find robot "):
+                    business = (
+                        E.CONFIG_REQUIRED,
+                        "Device key does not identify a frame",
+                        503,
+                        "device_key_invalid",
+                    )
+                elif status == 404 and message.startswith("can not find method "):
+                    business = (
+                        E.UNSUPPORTED_CAPABILITY,
+                        "Cloud method not found",
+                        422,
+                        "method_not_found",
+                    )
+            if business:
+                code, safe_message, local_status, kind = business
+                raise FlowError(
+                    code,
+                    safe_message,
+                    local_status,
+                    details={
+                        "http_status": status,
+                        "failure_kind": kind,
+                        "retryable": False,
+                        "write_outcome": "rejected" if write else "read_only",
+                    },
+                )
+            if status != 200:
+                limited = status == 429
+                rejected = 400 <= status < 500
+                uncertain = write and not rejected
+                details = {
+                    "http_status": status,
+                    "retryable": limited or (not write and status >= 500),
+                    "write_outcome": "unknown"
+                    if uncertain
+                    else ("rejected" if write else "read_only"),
+                }
+                if limited:
+                    delay = self._retry_after(response.headers.get("Retry-After"))
+                    details["retry_after_seconds"] = delay
+                    with self.lock:
+                        self.cooldown_until = max(
+                            self.cooldown_until, time.monotonic() + delay
+                        )
+                raise FlowError(
+                    E.RATE_LIMITED
+                    if limited
+                    else (E.WRITE_RESULT_UNKNOWN if uncertain else E.CLOUD_UNAVAILABLE),
+                    "Device cloud request failed",
+                    429 if limited else 502,
+                    details=details,
+                )
+            if binary:
+                if len(response.content) > 20 * 1024 * 1024:
+                    raise FlowError(E.INVALID_REQUEST, "Cloud image exceeds size limit")
+                return response.content
+            if (
+                not isinstance(value, dict)
+                or value.get("success") is False
+                or ("message" in value and "id" not in value)
             ):
-                raise ValueError()
+                raise FlowError(
+                    E.WRITE_RESULT_UNKNOWN if write else E.CLOUD_UNAVAILABLE,
+                    "Invalid device cloud response",
+                    502,
+                    details={
+                        "failure_kind": "invalid_response",
+                        "retryable": not write,
+                        "write_outcome": "unknown" if write else "read_only",
+                    },
+                )
             return value
-        except ValueError:
+        finally:
-            raise FlowError(
+            response.close()
-                E.WRITE_RESULT_UNKNOWN if write else E.CLOUD_UNAVAILABLE,
-                "Invalid device cloud response",
-                502,
-            ) from None
 
 
 class KokonnaClient:
@@ -118,7 +275,7 @@ class KokonnaClient:
     def upload(self, path, name):
         self.guard()
         value = guooscar_protocol.upload(self.transport, path.read_bytes(), name)
-        if not isinstance(value.get("id"), int) or value["id"] <= 0:
+        if type(value.get("id")) is not int or value["id"] <= 0:
             raise FlowError(E.WRITE_RESULT_UNKNOWN, "Upload ID not confirmed", 502)
         return value["id"]
 

pigway_frame_flow/errors.py

@@ -11,6 +11,7 @@ class ErrorCode(StrEnum):
     UNSUPPORTED_CAPABILITY = "UNSUPPORTED_CAPABILITY"
     RENDER_FAILED = "RENDER_FAILED"
     UPLOAD_FAILED = "UPLOAD_FAILED"
+    DISPLAY_NOT_CONFIRMED = "DISPLAY_NOT_CONFIRMED"
     WRITE_RESULT_UNKNOWN = "WRITE_RESULT_UNKNOWN"
     RATE_LIMITED = "RATE_LIMITED"
     INTERNAL_ERROR = "INTERNAL_ERROR"
@@ -22,6 +23,7 @@ class ErrorCode(StrEnum):
 
 
 class FlowError(Exception):
-    def __init__(self, code: ErrorCode, message: str, status: int = 400):
+    def __init__(self, code: ErrorCode, message: str, status: int = 400, details=None):
         self.code, self.message, self.status = code, message, status
+        self.details = details or {}
         super().__init__(message)

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/extensions/webhooks.py

@@ -39,12 +39,13 @@ class Webhooks:
         db = self.service.db
         for sub in db.all("SELECT * FROM webhook_subscriptions WHERE enabled=1"):
             types = json.loads(sub["event_types"])
+            if not types:
+                continue
+            placeholders = ",".join("?" for _ in types)
             for event in db.all(
-                "SELECT * FROM events e WHERE created_at>=? AND NOT EXISTS (SELECT 1 FROM webhook_deliveries d WHERE d.event_id=e.id AND d.subscription_id=?) ORDER BY created_at LIMIT 500",
+                f"SELECT * FROM events e WHERE created_at>=? AND event_type IN ({placeholders}) AND NOT EXISTS (SELECT 1 FROM webhook_deliveries d WHERE d.event_id=e.id AND d.subscription_id=?) ORDER BY created_at LIMIT 500",
-                (sub["created_at"], sub["id"]),
+                (sub["created_at"], *types, sub["id"]),
             ):
-                if event["event_type"] not in types:
-                    continue
                 db.execute(
                     "INSERT OR IGNORE INTO webhook_deliveries VALUES(?,?,'QUEUED',0,?,NULL)",
                     (sub["id"], event["id"], now_iso()),
@@ -137,6 +138,7 @@ def install_webhooks(app, service):
         allowed = {
             "operation.completed",
             "operation.failed",
+            "operation.blocked",
             "display.changed",
             "device.online",
             "device.offline",

pigway_frame_flow/models.py

@@ -177,7 +177,17 @@ class OperationResult(BaseModel):
     deferred: bool = False
 
 
+class RecoveryState(BaseModel):
+    state: Literal["checking", "manual_review", "resolved"]
+    reason: str
+    first_checked_at: str
+    last_checked_at: str
+    checks: int
+    requires_manual_review: bool
+
+
 class Operation(BaseModel):
+    recovery: RecoveryState | None = None
     operation_id: str
     status: OperationStatus
     device_id: str
@@ -255,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
@@ -323,7 +336,24 @@ class History(BaseModel):
     timestamp: str
 
 
+class GalleryDestination(BaseModel):
+    id: str
+    adapter: str
+    name: str
+    storage: Literal["cloud", "local"]
+    connected: bool = False
+    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
@@ -336,7 +366,7 @@ class SettingsView(BaseModel):
 
 class Health(BaseModel):
     status: str
-    version: str = "0.1.0"
+    version: str = "0.1.16"
 
 
 class Readiness(BaseModel):
@@ -365,8 +395,8 @@ class RestoreRequest(StrictModel):
 
 
 class Version(BaseModel):
-    product: str = "Pigway Frame Flow"
+    product: str = "PIGWay Frame Flow"
-    version: str = "0.1.0"
+    version: str = "0.1.16"
     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,7 +28,9 @@ 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)
     recursive: bool = True
     enabled: bool = True
@@ -77,6 +80,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 +110,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 +155,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 +199,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 +217,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 +296,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 +313,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 +323,7 @@ class PhotoSources:
                 refresh=refresh,
                 space=source.people_space,
             )
-            if source.people_filter
+            if source.people_filter and source.kind == "local"
             else None
         )
         items = []
@@ -406,6 +443,58 @@ 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
+                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,
+                        "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,7 +557,7 @@ 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
 
     def read(self, source_id, item_id=None, *, target_size=(1200, 1600)):
@@ -526,6 +615,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
 

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):

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:
+    while draw.textlength(text, font=font) > available and len(values[2]) > 2:
-        values[0] = values[0].rstrip("…")[:-1] + "…"
+        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,65 +149,85 @@ 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(),),
             ):
-                job = JobInput.model_validate_json(row["payload"])
+                try:
-                slot = row["next_run"]
+                    job = JobInput.model_validate_json(row["payload"])
-                if self.db.one(
+                    slot = row["next_run"]
-                    "SELECT * FROM job_runs WHERE job_id=? AND scheduled_at=?",
+                    if self.db.one(
-                    (row["id"], slot),
+                        "SELECT * FROM job_runs WHERE job_id=? AND scheduled_at=?",
-                ):
+                        (row["id"], slot),
-                    continue
+                    ):
-                # Skip overdue tasks (>5 minutes): avoid an unexpected artwork
+                        continue
-                # overwrite after downtime. One-time tasks are retired too.
+                    # Skip overdue tasks (>5 minutes): avoid an unexpected artwork
-                late = (current - datetime.fromisoformat(slot)).total_seconds() > 300
+                    # overwrite after downtime. One-time tasks are retired too.
-                operation_id = None
+                    late = (
-                if not late:
+                        current - datetime.fromisoformat(slot)
-                    action = "restore" if job.source.type == "restore" else "display"
+                    ).total_seconds() > 300
-                    payload = (
+                    operation_id = None
-                        {}
+                    if not late:
-                        if isinstance(job.source, RestoreContent)
+                        action = (
-                        else DisplayRequest(
+                            "restore" if job.source.type == "restore" else "display"
-                            device_id=job.device_id,
+                        )
-                            content=job.source,
+                        payload = (
-                            options=Options(
+                            {}
-                                duration=job.display_duration,
+                            if isinstance(job.source, RestoreContent)
-                                restore_previous=job.restore_previous,
+                            else DisplayRequest(
-                                priority=job.priority,
+                                device_id=job.device_id,
-                                cleanup_unstarred=job.cleanup_unstarred,
+                                content=job.source,
+                                options=Options(
+                                    duration=job.display_duration,
+                                    restore_previous=job.restore_previous,
+                                    priority=job.priority,
+                                    cleanup_unstarred=job.cleanup_unstarred,
+                                ),
+                            ).model_dump(mode="json")
+                        )
+                        if action == "display":
+                            payload = self.upload_retries.scheduled_payload(
+                                row["id"], payload
+                            )
+                        operation_id = self.service.submit(
+                            action,
+                            payload,
+                            job.device_id,
+                            "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(
+                        mode="json"
+                    )
+                    with self.db.transaction() as tx:
+                        tx.execute(
+                            "INSERT OR IGNORE INTO job_runs VALUES(?,?,?)",
+                            (row["id"], slot, operation_id),
+                        )
+                        tx.execute(
+                            "UPDATE jobs SET payload=?,enabled=?,next_run=?,last_run=?,last_result=? WHERE id=?",
+                            (
+                                encode(updated),
+                                int(enabled),
+                                following,
+                                now_iso(),
+                                "SKIPPED_OVERDUE" if late else operation_id,
+                                row["id"],
                             ),
-                        ).model_dump(mode="json")
+                        )
-                    )
+                except Exception:
-                    operation_id = self.service.submit(
+                    # Keep this slot pending for retry or the existing overdue policy.
-                        action,
+                    # A single device must not prevent other jobs or queue consumption.
-                        payload,
+                    logging.getLogger("frame-flow").error(
-                        job.device_id,
+                        "Scheduled job failed; details suppressed"
-                        "scheduler",
-                        "schedule-" + uuid4().hex,
-                        "job-" + row["id"] + "-" + slot,
-                    )
-                following = next_run(job.schedule, current)
-                enabled = bool(following)
-                updated = job.model_copy(update={"enabled": enabled}).model_dump(
-                    mode="json"
-                )
-                with self.db.transaction() as tx:
-                    tx.execute(
-                        "INSERT OR IGNORE INTO job_runs VALUES(?,?,?)",
-                        (row["id"], slot, operation_id),
-                    )
-                    tx.execute(
-                        "UPDATE jobs SET payload=?,enabled=?,next_run=?,last_run=?,last_result=? WHERE id=?",
-                        (
-                            encode(updated),
-                            int(enabled),
-                            following,
-                            now_iso(),
-                            "SKIPPED_OVERDUE" if late else operation_id,
-                            row["id"],
-                        ),
                     )
             for row in self.db.all(
                 "SELECT * FROM playlists WHERE next_run<=?", (current.isoformat(),)
@@ -269,6 +295,9 @@ class Scheduler:
     def run(self):
         while not self.stop_event.is_set():
             try:
+                # Resolve late sync before submitting due jobs: a write lock
+                # otherwise makes tick fail before reconciliation can run.
+                self.service.sync()
                 self.tick()
                 self.service.expire()
                 self.service.cloud_library.sweep()

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

@@ -27,6 +27,11 @@ class Settings:
         default_factory=lambda: secret("FRAME_FLOW_TOKEN"), repr=False
     )
     additional_secrets: list[str] = field(default_factory=list, repr=False)
+    storage_name: str = field(
+        default_factory=lambda: (
+            os.getenv("FRAME_FLOW_STORAGE_NAME", "NAS").strip() or "NAS"
+        )
+    )
     device_id: str = "living-room"
     timezone: str = "Asia/Shanghai"
     cors_origins: list[str] = field(
@@ -51,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/storage/database.py

@@ -31,6 +31,7 @@ class Database:
         CREATE TABLE IF NOT EXISTS image_sources (device_id TEXT, image_id INTEGER, asset_id TEXT, operation_id TEXT, payload TEXT NOT NULL, PRIMARY KEY(device_id,image_id));
         CREATE TABLE IF NOT EXISTS app_config (key TEXT PRIMARY KEY, payload TEXT NOT NULL);
         CREATE TABLE IF NOT EXISTS playlists (id TEXT PRIMARY KEY, payload TEXT, position INTEGER, next_run TEXT);
+        CREATE TABLE IF NOT EXISTS operation_recovery (operation_id TEXT PRIMARY KEY, state TEXT NOT NULL, reason TEXT NOT NULL, first_checked_at TEXT NOT NULL, last_checked_at TEXT NOT NULL, checks INTEGER NOT NULL);
         CREATE TABLE IF NOT EXISTS operations (
             id TEXT PRIMARY KEY, status TEXT NOT NULL, action TEXT NOT NULL,
             payload TEXT NOT NULL, device_id TEXT NOT NULL, client_id TEXT NOT NULL,

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(){localStorage.removeItem('ff-login');state.token='';state.csrf='';state.settings=null;state.devices=[];state.templates=[];}
+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(){state.settings=await api('/api/v1/settings');try{state.devices=await api('/api/v1/devices');}catch(error){state.devices=[];toast(error.message);}state.templates=await api('/api/v1/templates');state.device=state.devices[0]?.id||state.device;}
+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 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!=='cron')return t(type);return state.lang==='zh'?'高级规则（Cron）':'Advanced rule (Cron)';}
+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(['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 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(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 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,28 +26,64 @@ 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();
 }
 function bind(id,fn){const element=$('#'+id);if(element)element.onclick=async event=>{try{element.disabled=true;await fn(event);}catch(e){toast(e.message);}finally{element.disabled=false;}};}
 function busy(fn){return async event=>{try{await fn(event);}catch(e){toast(e.message);}};}
 function applyTheme(){const dark=state.theme==='dark'||(state.theme==='system'&&matchMedia('(prefers-color-scheme:dark)').matches);document.documentElement.dataset.theme=dark?'dark':'light';}
-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':''}"><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('');}
+function revealCurrentNavigation(){const active=$('#nav .active'),sidebar=$('.sidebar');if(active&&matchMedia('(max-width:720px)').matches)sidebar.scrollLeft=active.offsetLeft-(sidebar.clientWidth-active.offsetWidth)/2;}
-function clearBlobs(){for(const url of state.blobs)URL.revokeObjectURL(url);state.blobs=[];}
+window.addEventListener('resize',revealCurrentNavigation);
-async function blobImage(img,path){try{const blob=await api(path,{binary:true});if(!img.isConnected)return;const url=URL.createObjectURL(blob);state.blobs.push(url);img.src=url;}catch{img.alt=t('apiError');}}
+function deviceNameForId(id){return deviceDisplayName(state.devices.find(d=>d.id===id)||{id,name:id});}
-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=>observer.observe(img));}
+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 notice(){return state.settings?.mock?`<div class="notice">${t('mock')}</div>`:'';}
+function operationClientLabel(client){return client==='admin'?tr('管理员','Administrator'):client==='scheduler'?tr('自动调度','Scheduler'):client;}
-async function navigate(page=state.page){state.page=icons[page]?page:'dashboard';location.hash=state.page;shell();clearBlobs();state.epoch++;const epoch=state.epoch;
+function operationErrorLabel(error){if(!error?.code)return '';const label=t(error.code);return label===error.code?t('error'):label;}
- if(!state.token){login();return;}
+function deviceDisplayName(device){const name=device.name||device.id;return device.id==='living-room'&&['living-room','Living room'].includes(name)?t('livingRoom'):name;}
- $('#main').innerHTML='<div class="spinner"></div>';
+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();}
- try{await views[state.page](epoch);if(epoch!==state.epoch)return;const enhance={dashboard:enhanceDashboard,templates:enhanceTemplates,gallery:enhanceGallery,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());}
+// 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']);
+function galleryDestinations(){
+ const configured=state.settings?.gallery_destinations;
+ const destinations=Array.isArray(configured)?configured:[{id:'cloud',adapter:'kokonna',name:'KoKonna',storage:'cloud',connected:true,supports_upload:true},{id:'local',adapter:'local-assets',name:state.settings?.storage_name||'NAS',storage:'local',connected:true,supports_upload:true}];
+ return destinations.filter(d=>d.connected&&d.supports_upload&&galleryDestinationAdapters.has(d.adapter));
 }
-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 galleryDestinationName(destination){return `${destination.name} ${t(destination.storage==='local'?'local':'cloudGallery')}`;}
+function imageLoading(img){
+ if(img.parentElement?.classList.contains('image-loading'))return img.parentElement;
+ const box=document.createElement('div');box.className='image-loading';
+ if(img.classList.contains('thumb'))box.classList.add('image-loading-thumb');
+ if(img.closest('.frame-demo, .image-viewer-viewport, .studio-region'))box.classList.add('image-loading-fill');
+ box.setAttribute('aria-busy','true');img.before(box);box.append(img);
+ const status=document.createElement('span');status.className='image-loading-status';status.setAttribute('role','status');status.setAttribute('aria-label',t('loading'));
+ const spinner=document.createElement('span');spinner.className='spinner';spinner.setAttribute('aria-hidden','true');status.append(spinner);box.append(status);return box;
+}
+async function blobImage(img,path){
+ const box=imageLoading(img);
+ try{
+  const blob=await api(path,{binary:true});if(!img.isConnected)return;
+  const url=URL.createObjectURL(blob);state.blobs.push(url);
+  // Keep the placeholder until the browser has decoded the image as well as fetched it.
+  img.src=url;await img.decode();if(!img.isConnected)return;box.replaceWith(img);
+ }catch{
+  box.setAttribute('aria-busy','false');box.classList.add('image-load-error');
+  const status=box.querySelector('.image-loading-status');status.removeAttribute('aria-label');status.textContent=t('imageLoadError');
+ }
+}
+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){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(){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');
@@ -59,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;}
@@ -75,25 +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 class="mini-art"><div class="sun"></div></div><span class="frame-label">${t('testLabel')}</span></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){let 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;state.gallery=items;$('#main').innerHTML=notice()+`<div class="section-heading"><div class="tabs"><button id="cloud-tab" class="${state.tab==='cloud'?'active':''}">${t('cloud')}</button><button id="local-tab" class="${state.tab==='local'?'active':''}">${t('local')}</button></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});});});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();});});},
+ 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,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 title="${esc(x.name)}">${esc(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 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"><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 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('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);}
-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);}
 $('#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();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.
@@ -101,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');
+ 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?'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>`);
+ 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','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(deviceDisplayName(state.devices.find(d=>d.id===job.device_id)||{id:job.device_id,name:job.device_id}))}</small></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

@@ -2,24 +2,25 @@
 const tr=(zh,en)=>state.lang==='zh'?zh:en;
 async function layoutStudioPage(){
  const assets=await api('/api/v1/assets?source=uploaded&limit=200');let selected=new Set(),plan=null;
- $('#main').innerHTML=`<div class="notice">${tr('一次选择 1–12 张图片，生成多图拼版或海报。AI 只接收文字与尺寸，不接收照片。预览不会上传到画框。','Choose 1–12 photos for a collage or poster. AI receives text and dimensions, never photos. Preview does not upload to the frame.')}</div><div class="columns"><section class="card"><h3>${tr('选择照片','Choose photos')}</h3><input id="studio-files" type="file" multiple accept="image/jpeg,image/png,image/webp"><p class="hint">${tr('可以一次上传多张，保留原始比例。或勾选已有本地照片。','Upload several photos at once, preserving aspect ratio, or select local photos.')}</p><div id="studio-assets" class="studio-assets">${assets.map(a=>`<label class="check-row"><input type="checkbox" value="${a.asset_id}">${esc(a.name)}</label>`).join('')}</div><div class="field"><label>${tr('标题','Title')}</label><input id="studio-title" maxlength="100"></div><div class="field"><label>${tr('底部文字','Footer text')}</label><textarea id="studio-message" maxlength="500"></textarea></div><div class="form-grid"><div class="field"><label>${tr('布局','Layout')}</label><select id="studio-style"><option value="grid">${tr('均匀拼版','Grid')}</option><option value="hero">${tr('一张主图＋多张附图','Hero with supporting photos')}</option><option value="poster">${tr('海报','Poster')}</option></select></div><div class="field"><label>${tr('方向','Orientation')}</label><select id="studio-orientation"><option value="portrait">${tr('竖向','Portrait')}</option><option value="landscape">${tr('横向','Landscape')}</option></select></div></div><div class="field"><label>${t('profile')}</label><select id="studio-profile"><option value="color">${t('color')}</option><option value="grayscale">${t('grayscale')}</option></select></div><label class="check-row"><input id="studio-ai" type="checkbox">${tr('使用 AI 排版（先在连接中心配置）','Use AI layout (configure in Connections first)')}</label><div class="field"><label>${tr('AI 排版要求','AI layout instructions')}</label><textarea id="studio-prompt" maxlength="1500" placeholder="${tr('例如：第一张作为主图，其余大小错落','Example: feature the first photo with smaller supporting photos')}"></textarea></div><div class="actions"><button id="studio-plan" class="primary">${tr('规划布局','Plan layout')}</button><button id="studio-render" disabled>${t('render')}</button></div><p class="hint">${tr('规划后可拖动照片区域或修改坐标尺寸。区域不能重叠，超出范围的布局会被拒绝。','After planning, drag photo regions or edit coordinates and sizes. Overlapping or out-of-bounds layouts are rejected.')}</p><div id="studio-region-editor"></div></section><section class="card"><h3>${t('preview')}</h3><div id="studio-layout"></div><div id="studio-preview" class="empty">${tr('先规划布局，再生成最终图片','Plan the layout, then render the final image')}</div><div class="actions"><button id="studio-display" disabled>${t('display')}</button><button id="studio-download" disabled>${t('download')}</button></div></section></div>`;
+ $('#main').innerHTML=`<div class="notice">${tr('一次选择 1–12 张图片，生成多图拼版或海报。AI 只接收文字与尺寸，不接收照片。预览不会上传到画框。','Choose 1–12 photos for a collage or poster. AI receives text and dimensions, never photos. Preview does not upload to the frame.')}</div><div class="columns"><section class="card"><h3>${tr('选择照片','Choose photos')}</h3><input id="studio-files" type="file" multiple accept="image/jpeg,image/png,image/webp"><p class="hint">${tr('可以一次上传多张，保留原始比例。或勾选已有本地照片。','Upload several photos at once, preserving aspect ratio, or select local photos.')}</p><div id="studio-assets" class="studio-assets">${assets.map(a=>`<label class="check-row"><input type="checkbox" value="${a.asset_id}">${esc(a.name)}</label>`).join('')}</div><div class="field"><label for="studio-title">${tr('标题','Title')}</label><input id="studio-title" maxlength="100"></div><div class="field"><label for="studio-message">${tr('底部文字','Footer text')}</label><textarea id="studio-message" maxlength="500"></textarea></div><div class="form-grid"><div class="field"><label for="studio-style">${tr('布局','Layout')}</label><select id="studio-style"><option value="grid">${tr('均匀拼版','Grid')}</option><option value="hero">${tr('一张主图＋多张附图','Hero with supporting photos')}</option><option value="poster">${tr('海报','Poster')}</option></select></div><div class="field"><label for="studio-orientation">${tr('方向','Orientation')}</label><select id="studio-orientation"><option value="portrait">${tr('竖向','Portrait')}</option><option value="landscape">${tr('横向','Landscape')}</option></select></div></div><div class="field"><label for="studio-profile">${t('profile')}</label><select id="studio-profile"><option value="color">${t('color')}</option><option value="grayscale">${t('grayscale')}</option></select></div><label class="check-row"><input id="studio-ai" type="checkbox">${tr('使用 AI 排版（先在连接中心配置）','Use AI layout (configure in Connections first)')}</label><div class="field"><label for="studio-prompt">${tr('AI 排版要求','AI layout instructions')}</label><textarea id="studio-prompt" maxlength="1500" placeholder="${tr('例如：第一张作为主图，其余大小错落','Example: feature the first photo with smaller supporting photos')}"></textarea></div><div class="actions"><button id="studio-plan" class="primary">${tr('规划布局','Plan layout')}</button><button id="studio-render" disabled>${t('render')}</button></div><p class="hint">${tr('规划后可拖动照片区域或修改坐标尺寸。区域不能重叠，超出范围的布局会被拒绝。','After planning, drag photo regions or edit coordinates and sizes. Overlapping or out-of-bounds layouts are rejected.')}</p><div id="studio-region-editor"></div></section><section class="card"><h3>${t('preview')}</h3><div id="studio-layout"></div><div id="studio-preview" class="empty">${tr('先规划布局，再生成最终图片','Plan the layout, then render the final image')}</div><div class="actions"><button id="studio-display" disabled>${t('display')}</button><button id="studio-download" disabled>${t('download')}</button></div></section></div>`;
  await autoCollagePanel();
  let rendered=null;
  const invalidate=()=>{rendered=null;$('#studio-display').disabled=true;$('#studio-download').disabled=true;};
  $('#studio-assets').onchange=()=>{selected=new Set([...document.querySelectorAll('#studio-assets input:checked')].map(x=>x.value));plan=null;$('#studio-render').disabled=true;invalidate();};
  $('#studio-files').onchange=busy(async()=>{const files=[...$('#studio-files').files];if(!files.length)return;const body=new FormData();files.forEach(f=>body.append('files',f));const uploaded=await api('/api/v1/layout/images',{method:'POST',body});for(const a of uploaded){const label=document.createElement('label');label.className='check-row';label.innerHTML=`<input type="checkbox" checked value="${a.asset_id}">${esc(a.name)}`;$('#studio-assets').append(label);}$('#studio-assets').onchange();toast(t('done'));});
- async function showPlan(){
+ function showPlan(){
-  const box=$('#studio-layout');box.innerHTML='';box.className='studio-canvas';box.style.aspectRatio=plan.width+'/'+plan.height;
+  const layout=plan;
-  $('#studio-region-editor').innerHTML=plan.regions.map((r,i)=>`<div class="field"><label>${tr('图片区域','Photo region')} ${i+1}</label><div class="region-fields">${['x','y','width','height'].map(k=>`<label>${k}<input data-region="${i}" data-key="${k}" type="number" value="${r[k]}" min="0"></label>`).join('')}</div></div>`).join('');
+  const box=$('#studio-layout');box.innerHTML='';box.className='studio-canvas';box.style.aspectRatio=layout.width+'/'+layout.height;
-  const update=(el,r)=>{el.style.left=(r.x/plan.width*100)+'%';el.style.top=(r.y/plan.height*100)+'%';el.style.width=(r.width/plan.width*100)+'%';el.style.height=(r.height/plan.height*100)+'%';};
+  $('#studio-region-editor').innerHTML=layout.regions.map((r,i)=>`<div class="field"><label>${tr('图片区域','Photo region')} ${i+1}</label><div class="region-fields">${['x','y','width','height'].map(k=>`<label>${k}<input data-region="${i}" data-key="${k}" type="number" value="${r[k]}" min="0"></label>`).join('')}</div></div>`).join('');
-  for(const [i,r] of plan.regions.entries()){
+  const update=(el,r)=>{el.style.left=(r.x/layout.width*100)+'%';el.style.top=(r.y/layout.height*100)+'%';el.style.width=(r.width/layout.width*100)+'%';el.style.height=(r.height/layout.height*100)+'%';};
-   const img=document.createElement('img');img.alt=tr('拖动图片区域','Drag photo region')+' '+(i+1);img.draggable=false;update(img,r);box.append(img);await blobImage(img,'/api/v1/assets/'+r.asset_id);
+  for(const [i,r] of layout.regions.entries()){
-   img.onpointerdown=e=>{e.preventDefault();img.setPointerCapture(e.pointerId);const start={x:e.clientX,y:e.clientY,rx:r.x,ry:r.y};img.onpointermove=ev=>{r.x=Math.max(0,Math.min(plan.width-r.width,Math.round(start.rx+(ev.clientX-start.x)*plan.width/box.clientWidth)));r.y=Math.max(150,Math.min(plan.height-120-r.height,Math.round(start.ry+(ev.clientY-start.y)*plan.height/box.clientHeight)));update(img,r);for(const el of document.querySelectorAll(`[data-region="${i}"]`))el.value=r[el.dataset.key];invalidate();};img.onpointerup=()=>{img.onpointermove=null;};};
+   const region=document.createElement('div');region.className='studio-region';region.dataset.regionIndex=String(i);update(region,r);box.append(region);const img=document.createElement('img');img.alt=tr('拖动图片区域','Drag photo region')+' '+(i+1);img.draggable=false;region.append(img);void blobImage(img,'/api/v1/assets/'+r.asset_id);
+   region.onpointerdown=e=>{if(plan!==layout)return;e.preventDefault();region.setPointerCapture(e.pointerId);const start={x:e.clientX,y:e.clientY,rx:r.x,ry:r.y};region.onpointermove=ev=>{if(plan!==layout)return;r.x=Math.max(0,Math.min(layout.width-r.width,Math.round(start.rx+(ev.clientX-start.x)*layout.width/box.clientWidth)));r.y=Math.max(150,Math.min(layout.height-120-r.height,Math.round(start.ry+(ev.clientY-start.y)*layout.height/box.clientHeight)));update(region,r);for(const el of document.querySelectorAll(`[data-region="${i}"]`))el.value=r[el.dataset.key];invalidate();};region.onpointerup=region.onpointercancel=()=>{region.onpointermove=null;};};
   }
-  document.querySelectorAll('[data-region]').forEach(el=>el.oninput=()=>{const r=plan.regions[Number(el.dataset.region)];r[el.dataset.key]=Number(el.value);update(box.children[Number(el.dataset.region)],r);invalidate();});
+  document.querySelectorAll('[data-region]').forEach(el=>el.oninput=()=>{if(plan!==layout)return;const r=layout.regions[Number(el.dataset.region)];r[el.dataset.key]=Number(el.value);update(box.children[Number(el.dataset.region)],r);invalidate();});
  }
  for(const id of ['studio-title','studio-message','studio-style','studio-orientation','studio-ai','studio-prompt','studio-profile'])$('#'+id).oninput=()=>{plan=null;$('#studio-render').disabled=true;invalidate();};
- bind('studio-plan',async()=>{plan=await api('/api/v1/layout/plan',{method:'POST',body:{asset_ids:[...selected],title:$('#studio-title').value,message:$('#studio-message').value,orientation:$('#studio-orientation').value,style:$('#studio-style').value,use_ai:$('#studio-ai').checked,prompt:$('#studio-prompt').value}});invalidate();await showPlan();$('#studio-render').disabled=false;});
+ bind('studio-plan',async()=>{plan=await api('/api/v1/layout/plan',{method:'POST',body:{asset_ids:[...selected],title:$('#studio-title').value,message:$('#studio-message').value,orientation:$('#studio-orientation').value,style:$('#studio-style').value,use_ai:$('#studio-ai').checked,prompt:$('#studio-prompt').value}});invalidate();showPlan();$('#studio-render').disabled=false;});
  bind('studio-render',async()=>{if(!plan)return;const accepted=await api('/api/v1/render',{method:'POST',body:{type:'template',template:$('#studio-style').value==='poster'?'poster':'collage',data:{layout:plan},profile:$('#studio-profile').value}});const op=await waitOperation(accepted.operation_id);rendered=op.result;$('#studio-preview').className='';$('#studio-preview').innerHTML='<img class="preview" id="studio-result" alt="Preview">';await blobImage($('#studio-result'),rendered.url);$('#studio-display').disabled=!liveWriteAllowed();$('#studio-download').disabled=false;});
  bind('studio-display',()=>displayDialog({type:'image',asset_id:rendered.asset_id}));bind('studio-download',()=>downloadImage(rendered.url,'frame-flow-layout.jpg'));
 }
@@ -28,34 +29,34 @@ 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>Endpoint</label><input id="ai-endpoint" type="url" value="${esc(config.endpoint)}" placeholder="https://…/v1/chat/completions"></div><div class="field"><label>Model</label><input id="ai-model" value="${esc(config.model)}"></div><div class="field"><label>${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>${tr('生成图保留天数','Generated image retention days')}</label><input id="storage-days" type="number" min="1" value="${p.generated_days}"></div><div class="field"><label>${tr('缓存保留天数','Cache retention days')}</label><input id="storage-cache-days" type="number" min="1" value="${p.cache_days}"></div><div class="field"><label>${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';});
+ 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';});
 }
 async function clientsPanel(){
- const clients=await api('/api/v1/clients');const scopes=['devices:read','images:read','display:write','templates:read','render:write','jobs:read','jobs:write','history:read'];const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>${tr('外部客户端权限','External client permissions')}</h3><p class="hint">${tr('网页继续使用账号登录。这里只为其他程序创建独立凭据，可随时撤销。','The web UI still uses account login. These credentials are for other programs and can be revoked.')}</p>${clients.map(c=>`<p>${esc(c.name)} · ${esc(c.client_id)} · ${t(c.enabled?'enabled':'disabled')} ${c.client_id!=='admin'&&c.enabled?`<button data-revoke="${esc(c.client_id)}">${tr('撤销','Revoke')}</button>`:''}</p>`).join('')}<form id="client-form"><div class="field"><label>Client ID</label><input id="client-id" required pattern="[a-z0-9-]{1,60}"></div><div class="field"><label>${t('name')}</label><input id="client-name" required></div>${scopes.map(s=>`<label class="check-row"><input type="checkbox" name="client-scope" value="${s}" ${['devices:read','display:write','templates:read','render:write'].includes(s)?'checked':''}>${s}</label>`).join('')}<button type="submit">${tr('创建客户端','Create client')}</button><div id="client-secret" class="notice" hidden></div></form>`;$('#main').append(card);document.querySelectorAll('[data-revoke]').forEach(b=>b.onclick=busy(async()=>{await api('/api/v1/clients/'+b.dataset.revoke,{method:'DELETE'});await navigate();}));$('#client-form').onsubmit=busy(async e=>{e.preventDefault();const r=await api('/api/v1/clients',{method:'POST',body:{client_id:$('#client-id').value,name:$('#client-name').value,permissions:[...document.querySelectorAll('[name="client-scope"]:checked')].map(x=>x.value)}});$('#client-secret').hidden=false;$('#client-secret').textContent=tr('仅显示一次，请保存：','Shown once; save it: ')+r.token;});
+ const clients=await api('/api/v1/clients');const scopes=['devices:read','images:read','display:write','templates:read','render:write','jobs:read','jobs:write','history:read'];const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>${tr('外部客户端权限','External client permissions')}</h3><p class="hint">${tr('网页继续使用账号登录。这里只为其他程序创建独立凭据，可随时撤销。','The web UI still uses account login. These credentials are for other programs and can be revoked.')}</p>${clients.map(c=>`<p>${esc(c.name)} · ${esc(c.client_id)} · ${t(c.enabled?'enabled':'disabled')} ${c.client_id!=='admin'&&c.enabled?`<button data-revoke="${esc(c.client_id)}">${tr('撤销','Revoke')}</button>`:''}</p>`).join('')}<form id="client-form"><div class="field"><label for="client-id">Client ID</label><input id="client-id" required pattern="[a-z0-9-]{1,60}"></div><div class="field"><label for="client-name">${t('name')}</label><input id="client-name" required></div>${scopes.map(s=>`<label class="check-row"><input type="checkbox" name="client-scope" value="${s}" ${['devices:read','display:write','templates:read','render:write'].includes(s)?'checked':''}>${s}</label>`).join('')}<button type="submit">${tr('创建客户端','Create client')}</button><div id="client-secret" class="notice" hidden></div></form>`;$('#main').append(card);document.querySelectorAll('[data-revoke]').forEach(b=>b.onclick=busy(async()=>{await api('/api/v1/clients/'+b.dataset.revoke,{method:'DELETE'});await navigate();}));$('#client-form').onsubmit=busy(async e=>{e.preventDefault();const r=await api('/api/v1/clients',{method:'POST',body:{client_id:$('#client-id').value,name:$('#client-name').value,permissions:[...document.querySelectorAll('[name="client-scope"]:checked')].map(x=>x.value)}});$('#client-secret').hidden=false;$('#client-secret').textContent=tr('仅显示一次，请保存：','Shown once; save it: ')+r.token;});
 }
 async function webhooksPanel(){
- const hooks=await api('/api/v1/webhooks');const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>Webhook</h3><p class="hint">${tr('HTTPS 地址须先加入设置中的允许主机。事件带 HMAC 签名，最多重试三次；接收端应按事件 ID 去重。','Add the HTTPS host to the Settings allowlist first. Events are HMAC signed, with up to three attempts; deduplicate by event ID.')}</p>${hooks.map(h=>`<p>${esc(h.callback_url)} <button data-hook-delete="${h.id}">${t('delete')}</button></p>`).join('')}<form id="hook-form"><div class="field"><label>Callback URL</label><input id="hook-url" type="url" required></div><div class="field"><label>${tr('事件（逗号分隔）','Events (comma separated)')}</label><input id="hook-events" value="operation.completed,operation.failed"></div><button type="submit">${t('save')}</button><p id="hook-secret"></p></form>`;$('#main').append(card);document.querySelectorAll('[data-hook-delete]').forEach(b=>b.onclick=busy(async()=>{await api('/api/v1/webhooks/'+b.dataset.hookDelete,{method:'DELETE'});await navigate();}));$('#hook-form').onsubmit=busy(async e=>{e.preventDefault();const r=await api('/api/v1/webhooks',{method:'POST',body:{callback_url:$('#hook-url').value,event_types:$('#hook-events').value.split(',').map(x=>x.trim()).filter(Boolean)}});$('#hook-secret').textContent=tr('签名密钥仅显示一次：','Signing key shown once: ')+r.signing_secret;});
+ const hooks=await api('/api/v1/webhooks');const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>Webhook</h3><p class="hint">${tr('HTTPS 地址须先加入设置中的允许主机。事件带 HMAC 签名，最多重试三次；接收端应按事件 ID 去重。','Add the HTTPS host to the Settings allowlist first. Events are HMAC signed, with up to three attempts; deduplicate by event ID.')}</p>${hooks.map(h=>`<p>${esc(h.callback_url)} <button data-hook-delete="${h.id}">${t('delete')}</button></p>`).join('')}<form id="hook-form"><div class="field"><label for="hook-url">Callback URL</label><input id="hook-url" type="url" required></div><div class="field"><label for="hook-events">${tr('事件（逗号分隔）','Events (comma separated)')}</label><input id="hook-events" value="operation.completed,operation.failed"></div><button type="submit">${t('save')}</button><p id="hook-secret"></p></form>`;$('#main').append(card);document.querySelectorAll('[data-hook-delete]').forEach(b=>b.onclick=busy(async()=>{await api('/api/v1/webhooks/'+b.dataset.hookDelete,{method:'DELETE'});await navigate();}));$('#hook-form').onsubmit=busy(async e=>{e.preventDefault();const r=await api('/api/v1/webhooks',{method:'POST',body:{callback_url:$('#hook-url').value,event_types:$('#hook-events').value.split(',').map(x=>x.trim()).filter(Boolean)}});$('#hook-secret').textContent=tr('签名密钥仅显示一次：','Signing key shown once: ')+r.signing_secret;});
 }
 async function externalProvidersPanel(){
- const providers=await api('/api/v1/providers/external');const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>${tr('日历、家庭状态与监控','Calendars, home state and monitoring')}</h3><p class="hint">${tr('Google Calendar 使用 OAuth Token；家庭日历可用 ICS。Home Assistant 和 NAS/树莓派/服务器监控可以通过只读 JSON 接口提供数据，不访问外部数据库。LAN 访问必须明确开启。','Google Calendar uses an OAuth token; family calendars can use ICS. Home Assistant and NAS/Pi/server monitoring supply read-only JSON data without database access. LAN access requires explicit opt-in.')}</p>${providers.map(p=>`<p>${esc(p.name)} · ${esc(p.kind)} <button data-provider-read="${p.id}">${tr('读取','Read')}</button><button data-provider-job="${p.id}">${tr('创建展示任务','Create display job')}</button></p>`).join('')}<form id="provider-form"><div class="field"><label>ID</label><input id="provider-id" required pattern="[a-z0-9-]{1,60}"></div><div class="field"><label>${t('name')}</label><input id="provider-name" required></div><div class="field"><label>${tr('类型','Type')}</label><select id="provider-kind"><option value="google-calendar">Google Calendar</option><option value="ics">ICS · ${tr('家庭日历','Family calendar')}</option><option value="home-assistant">Home Assistant</option><option value="http-json">HTTP JSON · NAS / Pi / Server</option></select></div><div class="field"><label>${tr('地址（Google 日历填写 Calendar ID）','URL (Calendar ID for Google)')}</label><input id="provider-url" required></div><div class="field"><label>${tr('Token（可选）','Token (optional)')}</label><input id="provider-key" type="password" autocomplete="off"></div><label class="check-row"><input id="provider-lan" type="checkbox">${tr('允许访问指定 LAN 地址','Allow access to this LAN address')}</label><button type="submit">${t('save')}</button></form><pre id="provider-result"></pre>`;$('#main').append(card);$('#provider-form').onsubmit=busy(async e=>{e.preventDefault();const id=$('#provider-id').value;await api('/api/v1/providers/external/'+id,{method:'PUT',body:{kind:$('#provider-kind').value,name:$('#provider-name').value,endpoint:$('#provider-url').value,allow_insecure_lan:$('#provider-lan').checked}});const key=$('#provider-key').value;$('#provider-key').value='';if(key)await api('/api/v1/providers/external/'+id+'/key',{method:'PUT',body:{key}});await navigate();});document.querySelectorAll('[data-provider-read]').forEach(b=>b.onclick=busy(async()=>{$('#provider-result').textContent=JSON.stringify(await api('/api/v1/providers/external/'+b.dataset.providerRead+'/data'),null,2);}));document.querySelectorAll('[data-provider-job]').forEach(b=>b.onclick=busy(async()=>{await api('/api/v1/jobs',{method:'POST',body:{device_id:state.device,name:tr('外部信息板','External dashboard'),enabled:false,schedule:{type:'daily',time:'07:00'},source:{type:'provider',provider_id:b.dataset.providerJob,template:'daily-dashboard',data:{title:tr('家庭信息','Home information')}},display_duration:0,restore_previous:false,priority:50}});await navigate('automation');}));
+ const providers=await api('/api/v1/providers/external');const card=document.createElement('section');card.className='card';card.innerHTML=`<h3>${tr('日历、家庭状态与监控','Calendars, home state and monitoring')}</h3><p class="hint">${tr('Google Calendar 使用 OAuth Token；家庭日历可用 ICS。Home Assistant 和 NAS/树莓派/服务器监控可以通过只读 JSON 接口提供数据，不访问外部数据库。LAN 访问必须明确开启。','Google Calendar uses an OAuth token; family calendars can use ICS. Home Assistant and NAS/Pi/server monitoring supply read-only JSON data without database access. LAN access requires explicit opt-in.')}</p>${providers.map(p=>`<p>${esc(p.name)} · ${esc(p.kind)} <button data-provider-read="${p.id}">${tr('读取','Read')}</button><button data-provider-job="${p.id}">${tr('创建展示任务','Create display job')}</button></p>`).join('')}<form id="provider-form"><div class="field"><label for="provider-id">ID</label><input id="provider-id" required pattern="[a-z0-9-]{1,60}"></div><div class="field"><label for="provider-name">${t('name')}</label><input id="provider-name" required></div><div class="field"><label for="provider-kind">${tr('类型','Type')}</label><select id="provider-kind"><option value="google-calendar">Google Calendar</option><option value="ics">ICS · ${tr('家庭日历','Family calendar')}</option><option value="home-assistant">Home Assistant</option><option value="http-json">HTTP JSON · NAS / Pi / Server</option></select></div><div class="field"><label for="provider-url">${tr('地址（Google 日历填写 Calendar ID）','URL (Calendar ID for Google)')}</label><input id="provider-url" required></div><div class="field"><label for="provider-key">${tr('Token（可选）','Token (optional)')}</label><input id="provider-key" type="password" autocomplete="off"></div><label class="check-row"><input id="provider-lan" type="checkbox">${tr('允许访问指定 LAN 地址','Allow access to this LAN address')}</label><button type="submit">${t('save')}</button></form><pre id="provider-result"></pre>`;$('#main').append(card);$('#provider-form').onsubmit=busy(async e=>{e.preventDefault();const id=$('#provider-id').value;await api('/api/v1/providers/external/'+id,{method:'PUT',body:{kind:$('#provider-kind').value,name:$('#provider-name').value,endpoint:$('#provider-url').value,allow_insecure_lan:$('#provider-lan').checked}});const key=$('#provider-key').value;$('#provider-key').value='';if(key)await api('/api/v1/providers/external/'+id+'/key',{method:'PUT',body:{key}});await navigate();});document.querySelectorAll('[data-provider-read]').forEach(b=>b.onclick=busy(async()=>{$('#provider-result').textContent=JSON.stringify(await api('/api/v1/providers/external/'+b.dataset.providerRead+'/data'),null,2);}));document.querySelectorAll('[data-provider-job]').forEach(b=>b.onclick=busy(async()=>{await api('/api/v1/jobs',{method:'POST',body:{device_id:state.device,name:tr('外部信息板','External dashboard'),enabled:false,schedule:{type:'daily',time:'07:00'},source:{type:'provider',provider_id:b.dataset.providerJob,template:'daily-dashboard',data:{title:tr('家庭信息','Home information')}},display_duration:0,restore_previous:false,priority:50}});await navigate('automation');}));
 }
 async function officialWidgetControls(info,data){
- const panel=document.createElement('section');panel.className='card';panel.innerHTML=`<h3>${tr('订阅管理','Subscription management')}</h3><p class="hint">${tr('这与本地模板独立。请选择官方目录中的小组件，填写其参数后再确认。取消订阅不会自动恢复之前的照片。','This is separate from local templates. Choose a widget from the official catalog and fill its parameters before confirming. Cancelling does not automatically restore a previous photo.')}</p><div class="field"><label>${tr('官方小组件','Official widget')}</label><select id="official-widget-choice">${data.catalog.map(w=>`<option value="${w.id}">${esc(w.name)}</option>`).join('')}</select></div><div id="official-widget-args"></div><div class="actions"><button id="official-widget-use" class="primary">${tr('确认使用','Apply widget')}</button><button id="official-widget-cancel">${tr('取消订阅','Cancel subscription')}</button></div>`;info.append(panel);const disabled=!data.configured||!liveWriteAllowed();$('#official-widget-use').disabled=disabled;$('#official-widget-cancel').disabled=disabled;
+ const panel=document.createElement('section');panel.className='card';panel.innerHTML=`<h3>${tr('订阅管理','Subscription management')}</h3><p class="hint">${tr('这与本地模板独立。请选择官方目录中的小组件，填写其参数后再确认。取消订阅不会自动恢复之前的照片。','This is separate from local templates. Choose a widget from the official catalog and fill its parameters before confirming. Cancelling does not automatically restore a previous photo.')}</p><div class="field"><label for="official-widget-choice">${tr('官方小组件','Official widget')}</label><select id="official-widget-choice">${data.catalog.map(w=>`<option value="${w.id}">${esc(w.name)}</option>`).join('')}</select></div><div id="official-widget-args"></div><div class="actions"><button id="official-widget-use" class="primary">${tr('确认使用','Apply widget')}</button><button id="official-widget-cancel">${tr('取消订阅','Cancel subscription')}</button></div>`;info.append(panel);const disabled=!data.configured||!liveWriteAllowed();$('#official-widget-use').disabled=disabled;$('#official-widget-cancel').disabled=disabled;
  const fields=()=>{const w=data.catalog.find(w=>w.id===Number($('#official-widget-choice').value));$('#official-widget-args').innerHTML=(w?.arg_keys||[]).map(k=>`<div class="field"><label>${esc(k)}</label><input data-widget-arg="${esc(k)}" maxlength="2000"></div>`).join('');};if(data.current)$('#official-widget-choice').value=data.current.id;fields();$('#official-widget-choice').onchange=fields;
  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>${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>${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>${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>${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>${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"><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>Endpoint</label><input id="image-ai-url" type="url" required value="${esc(conf.endpoint||'')}"></div><div class="field"><label>Model</label><input id="image-ai-model" required value="${esc(conf.model||'')}"></div><div class="field"><label>Size</label><select id="image-ai-size"><option>1024x1536</option><option>1536x1024</option><option>1024x1024</option></select></div><div class="field"><label>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>${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>Host</label><input id="mqtt-host" value="${esc(c.host)}"></div><div class="field"><label>Port</label><input id="mqtt-port" type="number" min="1" max="65535" value="${c.port}"></div><div class="field"><label>Topic</label><input id="mqtt-topic" value="${esc(c.topic)}"></div><div class="field"><label>${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'));});
+ 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'));});
 }
 
 async function autoCollagePanel(){

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>`;await blobImage($('#current-frame-image'),current.preview_url);}
+ 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'),current.preview_url);}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');});
 }
-async function enhanceGallery(){
+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);
+ 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'){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';const jobs=await api('/api/v1/jobs');for(const job of jobs){const option=document.createElement('option');option.value=job.id;option.textContent=job.name;$('#asset-job').append(option);}$('#asset-job').value=state.assetJob||'';$('#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();});}}
+ 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=()=>{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));};
+ 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('sourceUnknown'));});}});
+ 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>`);
+ 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"><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||'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='';};
+ $('#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-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=$('#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');});
+ $('#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,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_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){
+async 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');});
+ 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"><meta name="color-scheme" content="light dark"><title>Pigway Frame Flow</title><link rel="stylesheet" href="/ui/style.css"></head>
+<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.0</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>
+<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.16</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=gallery-layout-v0116"></script><script src="/ui/features.js?v=gallery-layout-v0116"></script><script src="/ui/extensions.js?v=gallery-layout-v0116"></script><script src="/ui/app.js?v=gallery-layout-v0116"></script></body></html>

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pigway-frame-flow"
-version = "0.1.0"
+version = "0.1.16"
 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/persistence-check.py

@@ -10,7 +10,7 @@ from urllib.request import Request, urlopen
 parser = argparse.ArgumentParser()
 parser.add_argument("mode", choices=["record", "check"])
 args = parser.parse_args()
-base = os.getenv("FRAME_FLOW_URL", "http://127.0.0.1:18787").rstrip("/")
+base = os.getenv("FRAME_FLOW_URL", "http://127.0.0.1:6005").rstrip("/")
 token = os.getenv("FRAME_FLOW_TOKEN", "")
 if not token:
     for line in Path(".env").read_text().splitlines():

scripts/production-deploy.py

@@ -37,6 +37,7 @@ class Deploy:
         self.lock_id = None
         self.state = None
         self.old_image = None
+        self.old_image_tag = ""
         self.secret_values = [
             self.env[key]
             for key in (
@@ -69,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))
@@ -117,20 +125,9 @@ class Deploy:
                 or not m.get("RW")
             ):
                 raise ValueError("Production mount mismatch: " + key)
-        photos = self.env.get("PROD_PHOTOS_DIR")
+        if self.env.get("PROD_PHOTOS_DIR") or "/photos" in mounts:
-        if "/photos" in mounts and (
+            raise ValueError("Filesystem photo mounts are retired; use the Photos API")
-            not photos
+        if set(mounts) != {"/data", "/config"}:
-            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()):
             raise ValueError("Unrecognized persistent mount; review before adopting CD")
         bindings = old["HostConfig"].get("PortBindings", {}).get("18787/tcp")
         if bindings != [
@@ -179,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"]
@@ -196,6 +183,7 @@ class Deploy:
         ):
             raise ValueError("Production user/restart policy differs from repository")
         self.old_image = old["Image"]
+        self.old_image_tag = old["Config"].get("Image", "")
         volume = self.run(
             "volume", "inspect", self.env["PROD_STATE_VOLUME"], check=False
         )
@@ -335,6 +323,12 @@ class Deploy:
     def rollback(self, previous):
         self.activate(previous)
         self.verify(previous)
+        self.run(
+            "image",
+            "tag",
+            previous["services"]["pigway-frame-flow"]["image"],
+            self.env["PROD_IMAGE_REPO"] + ":latest",
+        )
         print("ROLLBACK VERIFIED", flush=True)
 
     def secret_config(self):
@@ -390,10 +384,16 @@ class Deploy:
             command += ["--build-arg", key + "=" + value]
         self.run(*command, str(ROOT))
         service = config["services"]["pigway-frame-flow"]
-        service["image"] = image
+        latest = self.env["PROD_IMAGE_REPO"] + ":latest"
+        self.run("image", "tag", image, latest)
+        service["image"] = latest
         proposed = self.secret_config()
         service["environment"].update(proposed)
-        for key in ("SYNOLOGY_PHOTOS_URL", "SYNOLOGY_PHOTOS_CERT_SHA256"):
+        for key in (
+            "SYNOLOGY_PHOTOS_URL",
+            "SYNOLOGY_PHOTOS_CERT_SHA256",
+            "FRAME_FLOW_STORAGE_NAME",
+        ):
             if self.env.get(key):
                 service["environment"][key] = self.env[key]
         service["environment"].update(
@@ -664,6 +664,7 @@ class Deploy:
             self.state["status"] = "success"
             self.state_io(self.state)
             print("BOOTSTRAP VERIFIED", flush=True)
+            self.cleanup_images()
         except BaseException:
             print("BOOTSTRAP FAILED", flush=True)
             self.diagnostics()
@@ -723,6 +724,68 @@ class Deploy:
         text = re.sub(r"https?://[^\s\"'<>]+", "[REDACTED-URL]", text)
         print("Scoped container logs (redacted):", text, flush=True)
 
+    def cleanup_images(self):
+        """Keep only latest after verification; protect unrelated container images."""
+        try:
+            protected = set()
+            referenced_tags = set()
+            container_ids = self.run("ps", "-aq").stdout.decode().split()
+            if container_ids:
+                containers = json.loads(self.run("inspect", *container_ids).stdout)
+                protected.update(container["Image"] for container in containers)
+                referenced_tags.update(
+                    container.get("Config", {}).get("Image", "")
+                    for container in containers
+                )
+            repo = self.env["PROD_IMAGE_REPO"]
+            image_ids = (
+                self.run("image", "ls", "--no-trunc", "-q", repo)
+                .stdout.decode()
+                .split()
+            )
+            if not image_ids:
+                return
+            images = json.loads(
+                self.run("image", "inspect", *sorted(set(image_ids))).stdout
+            )
+            removed = 0
+            for image in images:
+                tags = image.get("RepoTags") or []
+                # Shared images and unrelated tags are never cleanup targets.
+                if not tags:
+                    continue
+                if not all(
+                    re.fullmatch(
+                        re.escape(repo)
+                        + r":(?:latest|release-[0-9a-f]{40}-[0-9a-f]{8}(?:-rollback)?|rollback-[0-9a-f]{32})",
+                        tag,
+                    )
+                    for tag in tags
+                ):
+                    continue
+                latest = repo + ":latest"
+                if image["Id"] in protected:
+                    # Current production uses latest. Other containers retain
+                    # their referenced tags and images, even when stopped.
+                    if latest not in tags:
+                        continue
+                    tags = [
+                        tag
+                        for tag in tags
+                        if tag != latest and tag not in referenced_tags
+                    ]
+                if not tags:
+                    continue
+                result = self.run("image", "rm", *tags, check=False)
+                if result.returncode:
+                    print("IMAGE RETENTION: referenced image retained", flush=True)
+                else:
+                    removed += 1
+            print(f"IMAGE RETENTION: removed {removed} obsolete images", flush=True)
+        except Exception:
+            # Cleanup failure must never roll back an already verified deployment.
+            print("IMAGE RETENTION WARNING: cleanup deferred", flush=True)
+
     def deploy(self):
         previous = self.preflight()
         self.lock()
@@ -732,7 +795,15 @@ class Deploy:
             # Refresh baseline under the daemon-level lock.
             previous = self.preflight()
             version = self.verify(previous)
-            pin = self.env["PROD_IMAGE_REPO"] + ":rollback-" + self.owner
+            release = self.old_image_tag.removesuffix("-rollback")
+            if re.fullmatch(
+                re.escape(self.env["PROD_IMAGE_REPO"])
+                + r":release-[0-9a-f]{40}-[0-9a-f]{8}",
+                release,
+            ):
+                pin = release + "-rollback"
+            else:
+                pin = self.env["PROD_IMAGE_REPO"] + ":rollback-" + self.owner
             self.run("image", "tag", self.old_image, pin)
             candidate = self.build(json.loads(json.dumps(previous)))
             self.state = {
@@ -791,6 +862,10 @@ class Deploy:
             if safe_unlock:
                 self.unlock()
 
+        # The deployment lock itself references the old image. Release it
+        # before retention; other container references remain protected.
+        self.cleanup_images()
+
     def recover(self, manual=False):
         self.settings()
         lock = self.run(

scripts/run_local.py

@@ -40,5 +40,8 @@ os.environ["BUILD_COMMIT"] = (
 
 os.environ["BUILD_TIME"] = datetime.now(UTC).isoformat()
 uvicorn.run(
-    "pigway_frame_flow.main:app", host="127.0.0.1", port=18787, access_log=False
+    "pigway_frame_flow.main:app",
+    host="127.0.0.1",
+    port=int(os.getenv("WEB_PORT", "6005")),
+    access_log=False,
 )

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.16-" + 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-audit-regressions.cjs

@@ -1,3 +1,3 @@
 /* Mock vendor expiration must preserve first-party login and show reconnect. */
 const assert=require('assert'),{chromium}=require('playwright');
-(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();const errors=[];page.on('pageerror',e=>errors.push(e.message));await page.goto('http://127.0.0.1:18787');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));await page.route('**/api/v1/devices/*/widgets',r=>r.fulfill({status:401,json:{error:{code:'OFFICIAL_AUTH_REQUIRED',message:'Official account session expired',request_id:'fixture',details:{}}}}));await page.route('**/api/v1/devices/*/official/connection',r=>r.fulfill({json:{authorized:false,username:'fixture',robot_id:null,mock:true,devices:[]}}));await page.locator('[data-page="templates"]').click();await page.locator('.official-content-info summary').click();await page.locator('#official-login-form').waitFor();assert(await page.evaluate(()=>Boolean(state.token&&state.csrf)));assert(await page.evaluate(async()=>Boolean((await api('/api/v1/auth/me')).username)));await page.route('**/api/v1/test-first-party-expired',r=>r.fulfill({status:401,json:{error:{code:'UNAUTHORIZED',message:'Expired',request_id:'fixture',details:{}}}}));await page.evaluate(async()=>{try{await api('/api/v1/test-first-party-expired');}catch{}});assert(await page.evaluate(()=>state.token===''));assert(errors.length===0);await browser.close();console.log('Audit UI: official expiry preserves login, reconnect visible, own expiry clears login; PASS');})().catch(e=>{console.error(e.message);process.exit(1)});
+(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();const errors=[];page.on('pageerror',e=>errors.push(e.message));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));await page.route('**/api/v1/devices/*/widgets',r=>r.fulfill({status:401,json:{error:{code:'OFFICIAL_AUTH_REQUIRED',message:'Official account session expired',request_id:'fixture',details:{}}}}));await page.route('**/api/v1/devices/*/official/connection',r=>r.fulfill({json:{authorized:false,username:'fixture',robot_id:null,mock:true,devices:[]}}));await page.locator('[data-page="templates"]').click();await page.locator('.official-content-info summary').click();await page.locator('#official-login-form').waitFor();assert(await page.evaluate(()=>Boolean(state.token&&state.csrf)));assert(await page.evaluate(async()=>Boolean((await api('/api/v1/auth/me')).username)));await page.route('**/api/v1/test-first-party-expired',r=>r.fulfill({status:401,json:{error:{code:'UNAUTHORIZED',message:'Expired',request_id:'fixture',details:{}}}}));await page.evaluate(async()=>{try{await api('/api/v1/test-first-party-expired');}catch{}});assert(await page.evaluate(()=>state.token===''));assert(errors.length===0);await browser.close();console.log('Audit UI: official expiry preserves login, reconnect visible, own expiry clears login; PASS');})().catch(e=>{console.error(e.message);process.exit(1)});

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=>r.fulfill({contentType:'image/svg+xml',body:'<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="900"><rect width="1200" height="900" fill="#6c9c83"/><circle cx="600" cy="450" r="220" fill="#e9d9af"/></svg>'}));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-current.cjs

@@ -5,7 +5,7 @@ const assert=require('assert'),{chromium}=require('playwright');
  await page.route('**/api/v1/devices/*/images',r=>r.fulfill({json:[{image_id:1,name:'Current fixture',current:true,url:'/mock-image.jpg',created_at:null},{image_id:2,name:'Other fixture',current:false,url:'/mock-image.jpg',created_at:null}]}));
  page.on('request',r=>{if(r.method()==='POST'&&r.url().endsWith('/display'))writes++;});
  try{
- await page.goto('http://127.0.0.1:18787');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));
+ 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('[data-show="0"]').waitFor();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++;
  }

scripts/ui-gallery-destinations.cjs

@@ -0,0 +1,18 @@
+/* Mock-only: real writable destinations, concrete names and responsive labels. */
+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 browser=await chromium.launch({headless:true,executablePath:process.env.CHROME_EXECUTABLE||'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});
+ try{
+  const page=await browser.newPage();const errors=[];page.on('pageerror',e=>errors.push(e.message));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();
+  await page.evaluate(()=>{state.settings.storage_name='FixtureNAS';state.settings.gallery_destinations=[{id:'cloud',adapter:'kokonna',name:'KoKonna',storage:'cloud',connected:true,supports_upload:true},{id:'local',adapter:'local-assets',name:'FixtureNAS',storage:'local',connected:true,supports_upload:true},{id:'read-only-drive',adapter:'kokonna',name:'Read-only fixture',storage:'cloud',connected:true,supports_upload:false},{id:'offline-drive',adapter:'kokonna',name:'Offline fixture',storage:'cloud',connected:false,supports_upload:true},{id:'unimplemented-drive',adapter:'unimplemented',name:'Future fixture',storage:'cloud',connected:true,supports_upload:true}];});let checks=0;
+  for(const width of [320,390,768,1440])for(const lang of ['zh','en'])for(const theme of ['light','dark']){
+   await page.setViewportSize({width,height:900});await page.evaluate(({lang,theme})=>{state.lang=lang;document.documentElement.dataset.theme=theme;return navigate('gallery');},{lang,theme});
+   assert.equal(await page.locator('#cloud-tab').innerText(),lang==='zh'?'KoKonna 云端图库':'KoKonna cloud gallery');assert.equal(await page.locator('#local-tab').innerText(),lang==='zh'?'FixtureNAS 本地图库':'FixtureNAS Local gallery');assert.equal(await page.locator('[data-gallery-destination]').count(),2);assert(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));checks++;
+  }
+  await page.setViewportSize({width:320,height:740});await page.evaluate(()=>{state.settings.gallery_destinations.find(d=>d.id==='local').name='家庭照片存储服务器名称很长的NAS';return navigate('gallery');});assert(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));checks++;
+  await page.locator('#local-tab').click();assert.equal(await page.evaluate(()=>state.tab),'local');await page.locator('#cloud-tab').click();assert.equal(await page.evaluate(()=>state.tab),'cloud');checks++;
+  assert.deepEqual(errors,[]);console.log('Gallery destinations:',checks,'checks PASS; concrete labels, capability/connection/adapter gates, responsive layout and tab switching');
+ }finally{await browser.close();}
+})().catch(e=>{console.error(e.message);process.exit(1)});

scripts/ui-gallery-stars.cjs

@@ -6,10 +6,13 @@ const assert=require('assert'),{chromium}=require('playwright');
  await page.route('**/api/v1/assets/local-1/star',r=>{starred=r.request().postDataJSON().starred;return r.fulfill({json:{starred,expires_at:null}});});
  page.on('request',r=>{if(r.method()==='POST'&&r.url().endsWith('/display'))writes++;});
  try{
- await page.goto('http://127.0.0.1:18787');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));
+ 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-layout.cjs

@@ -1,3 +1,3 @@
 /* Mock history fixtures only; verifies long identifiers and detail actions. */
 const assert=require('assert'),{chromium}=require('playwright');
-(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();const op={operation_id:'a'.repeat(64),request_id:'b'.repeat(64),action:'render',device_id:'living-room',client_id:'user:way',created_at:'2026-10-05T00:28:05Z',status:'COMPLETED',result:{asset_id:'c'.repeat(64)}};await page.route('**/api/v1/operations',r=>r.fulfill({json:[op,op]}));await page.route('**/api/v1/operations/'+op.operation_id,r=>r.fulfill({json:op}));await page.goto('http://127.0.0.1:18787');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();let checks=0;for(const lang of ['zh','en'])for(const width of [1440,768,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="history"]').click();await page.locator('.history-actions button').first().waitFor();assert(await page.evaluate(()=>{const table=document.querySelector('.history-table');return table.querySelectorAll('th').length===7&&[...table.querySelectorAll('tbody tr')].every(row=>row.children.length===7&&row.lastElementChild.classList.contains('history-actions')&&row.lastElementChild.previousElementSibling.querySelector('button')===null)&&document.documentElement.scrollWidth<=innerWidth;}));await page.locator('.history-actions button').first().click();await page.locator('#modal[open]').waitFor();await page.locator('#modal-cancel').click();checks++;}await browser.close();console.log('History layout and detail dialog: '+checks+' passed');})().catch(e=>{console.error(e);process.exit(1)});
+(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();const op={operation_id:'a'.repeat(64),request_id:'b'.repeat(64),action:'render',device_id:'living-room',client_id:'user:way',created_at:'2026-10-05T00:28:05Z',status:'COMPLETED',result:{asset_id:'c'.repeat(64)}};await page.route('**/api/v1/operations',r=>r.fulfill({json:[op,op]}));await page.route('**/api/v1/operations/'+op.operation_id,r=>r.fulfill({json:op}));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();let checks=0;for(const lang of ['zh','en'])for(const width of [1440,768,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="history"]').click();await page.locator('.history-actions button').first().waitFor();assert(await page.evaluate(()=>{const table=document.querySelector('.history-table');return table.querySelectorAll('th').length===7&&[...table.querySelectorAll('tbody tr')].every(row=>row.children.length===7&&row.lastElementChild.classList.contains('history-actions')&&row.lastElementChild.previousElementSibling.querySelector('button')===null)&&document.documentElement.scrollWidth<=innerWidth;}));await page.locator('.history-actions button').first().click();await page.locator('#modal[open]').waitFor();await page.locator('#modal-cancel').click();checks++;}await browser.close();console.log('History layout and detail dialog: '+checks+' passed');})().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-image-loading.cjs

@@ -0,0 +1,39 @@
+/* Isolated Mock UI audit: delayed images stay inside their own placeholders. */
+const assert=require('assert');
+const fs=require('fs');
+const {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 browser=await chromium.launch({headless:true,executablePath:process.env.CHROME_EXECUTABLE||'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});
+ try{
+  const page=await browser.newPage();const errors=[];page.on('pageerror',e=>errors.push(e.message));
+  await page.route('**/api/v1/devices/*/images',r=>r.fulfill({json:[{image_id:1,name:'Loading fixture',url:'/ui-audit-image.svg',current:false}]}));
+  let release;let requested;
+  await page.route('**/ui-audit-image.svg*',async r=>{requested();await new Promise(resolve=>release=resolve);await r.fulfill({contentType:'image/svg+xml',body:'<svg xmlns="http://www.w3.org/2000/svg" width="300" height="400"><rect width="300" height="400" fill="#167253"/></svg>'});});
+  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();
+  let checks=0;
+  async function centered(){
+   const result=await page.locator('.image-loading').evaluate(box=>{
+    const spinner=box.querySelector('.spinner'),img=box.querySelector('img'),a=box.getBoundingClientRect(),b=spinner.getBoundingClientRect();
+    return {centered: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,hidden:getComputedStyle(img).visibility==='hidden',contained:box.querySelector('.image-loading-status').offsetParent===box,overflow:document.documentElement.scrollWidth>innerWidth};
+   });assert.deepStrictEqual(result,{centered:true,hidden:true,contained:true,overflow:false});checks++;
+   assert.equal(await page.locator('.spinner:not(.image-loading .spinner)').count(),0);checks++;
+  }
+  for(const width of [1440,768,390])for(const theme of ['light','dark']){
+   await page.setViewportSize({width,height:900});await page.evaluate(theme=>document.documentElement.dataset.theme=theme,theme);
+   const request=new Promise(resolve=>requested=resolve);await page.evaluate(()=>navigate('gallery'));await request;await centered();
+   const before=await page.locator('.image-loading').boundingBox();release();await page.waitForFunction(()=>document.querySelector('.thumb')?.naturalWidth===300&&!document.querySelector('.image-loading'));
+   const after=await page.locator('.thumb').boundingBox();assert(Math.abs(before.height-after.height)<1,'Thumbnail placeholder changes height');checks++;
+   const originalRequest=new Promise(resolve=>requested=resolve);await page.locator('[data-original]').click();await originalRequest;await centered();release();await page.waitForFunction(()=>document.querySelector('#original-image')?.naturalWidth===300&&!document.querySelector('.image-loading'));await page.locator('#modal-cancel').click();checks++;
+   await page.evaluate(async()=>{const img=document.querySelector('.thumb');await blobImage(img,'/ui-audit-missing-image');});
+   assert.equal(await page.locator('.image-load-error').count(),1);assert.equal(await page.locator('.image-load-error .spinner').count(),0);assert(await page.locator('.image-load-error').innerText());checks++;
+  }
+  await page.evaluate(()=>navigate('connections'));
+  assert.deepStrictEqual(await page.locator('#main input,#main select,#main textarea').evaluateAll(nodes=>nodes.filter(e=>e.checkVisibility()&&!e.labels.length&&!e.getAttribute('aria-label')&&!e.getAttribute('aria-labelledby')).map(e=>e.id)),[]);checks++;
+  assert.equal(await page.locator('nav [aria-current="page"]').count(),1);checks++;
+  const nav=await page.locator('nav button').evaluateAll(nodes=>nodes.map(e=>({height:e.getBoundingClientRect().height,nowrap:getComputedStyle(e).whiteSpace})));assert(nav.every(e=>e.height>=44&&e.nowrap==='nowrap'));checks++;
+  assert.deepStrictEqual(errors,[]);console.log('Image/UI consistency audit:',checks,'passed; desktop/tablet/mobile, light/dark; no page errors');
+ }finally{await browser.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,19 +9,23 @@ 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):[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=[];
+   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);if((x>1&&dy<7.5)||(y>1&&dx<7.5))close.push([controls[i].id,controls[j].id]);}
+   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]);}
-   return {overflow:document.documentElement.scrollWidth>innerWidth,close,small:innerWidth<=720?controls.filter(e=>e.r.height<43.5).map(e=>e.id):[]};
+   const dialog=document.querySelector('dialog[open]');const rect=dialog?.getBoundingClientRect();
-  });checks++;if(result.overflow||result.close.length||result.small.length)failures.push({label,...result});
+   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;});
+   return {clippedDialog,clippedNav,overflow:document.documentElement.scrollWidth>innerWidth,close,small:innerWidth<=720?controls.filter(e=>e.r.height<43.5).map(e=>e.id):[]};
+  });checks++;if(result.clippedDialog||result.clippedNav||result.overflow||result.close.length||result.small.length)failures.push({label,...result});
  }
- for(const width of [1440,768,390])for(const lang of ['zh','en'])for(const theme of ['light','dark']){
+ for(const {width,height} of viewports)for(const lang of ['zh','en'])for(const theme of ['light','dark']){
-  await page.setViewportSize({width,height:900});await page.evaluate(({lang,theme})=>{state.lang=lang;document.documentElement.dataset.theme=theme;shell();},{lang,theme});
+  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();
@@ -29,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, 12 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-layout.cjs

@@ -1,5 +1,5 @@
 /* All-page layout and daily-poetry checks; Mock only, no real device writes. */
 const assert=require('assert'),{chromium}=require('playwright');
-(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();let unintended=0;page.on('request',r=>{if(r.method()==='POST'&&/\/(jobs|playlists|display)$/.test(r.url()))unintended++;});const base='http://127.0.0.1:18787';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();assert(await page.evaluate(()=>state.settings.mock));let checks=0;for(const lang of ['zh','en'])for(const writable of [false,true]){const clean=await page.evaluate(({lang,writable})=>{const previous={lang:state.lang,settings:state.settings};state.lang=lang;state.settings={...state.settings,mock:false,write_enabled:writable};shell();const clean=notice()===''&&!document.querySelector('#connection')&&!document.querySelector('.sidebar-bottom .live-dot');state.lang=previous.lang;state.settings=previous.settings;shell();return clean;},{lang,writable});assert(clean,'Live-device status must not appear in either language');checks++;}for(const width of [1440,390])for(const theme of ['light','dark']){await page.setViewportSize({width,height:1000});await page.evaluate(theme=>{localStorage.setItem('ff-theme',theme);document.documentElement.dataset.theme=theme;},theme);for(const name of ['dashboard','gallery','photo-sources','upload','templates','automation','playlists','history','settings']){await page.locator(`[data-page="${name}"]`).click();await page.waitForTimeout(350);if(name==='settings')await page.locator('#image-host-form').waitFor();const result=await page.evaluate(()=>{const children=[...document.querySelector('#main').children].filter(x=>x.getBoundingClientRect().height>0);return {overflow:document.documentElement.scrollWidth>innerWidth,buttonGaps:[...document.querySelectorAll('#main button')].flatMap(b=>{const next=b.nextElementSibling;if(next?.tagName!=='BUTTON')return [];const a=b.getBoundingClientRect(),c=next.getBoundingClientRect();if(!a.width||!c.width)return [];return [Math.abs(a.top-c.top)<4?c.left-a.right:c.top-a.bottom];}),gaps:children.slice(1).map((x,i)=>x.getBoundingClientRect().top-children[i].getBoundingClientRect().bottom)};});const controls=await page.evaluate(()=>{const nodes=[...document.querySelectorAll('#main input:not([type="checkbox"]):not([type="radio"]),#main select,#main textarea,#main button')].filter(x=>{const r=x.getBoundingClientRect();return r.width&&r.height&&getComputedStyle(x).visibility!=='hidden';});const issues=[];for(let i=0;i<nodes.length;i++)for(let j=i+1;j<nodes.length;j++){const a=nodes[i].getBoundingClientRect(),b=nodes[j].getBoundingClientRect();const ox=Math.min(a.right,b.right)-Math.max(a.left,b.left),oy=Math.min(a.bottom,b.bottom)-Math.max(a.top,b.top);const dy=Math.max(a.top,b.top)-Math.min(a.bottom,b.bottom),dx=Math.max(a.left,b.left)-Math.min(a.right,b.right);if((ox>Math.min(a.width,b.width)/2&&dy>=0&&dy<8)||(oy>Math.min(a.height,b.height)/2&&dx>=0&&dx<8))issues.push({a:nodes[i].id,b:nodes[j].id,gap:ox>0?dy:dx});}return issues;});assert(controls.length===0,`${name} ${width} ${theme} controls ${JSON.stringify(controls)}`);checks++;
+(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();let unintended=0;page.on('request',r=>{if(r.method()==='POST'&&/\/(jobs|playlists|display)$/.test(r.url()))unintended++;});const base=process.env.FRAME_FLOW_URL||'http://127.0.0.1:6005';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();assert(await page.evaluate(()=>state.settings.mock));let checks=0;for(const lang of ['zh','en'])for(const writable of [false,true]){const clean=await page.evaluate(({lang,writable})=>{const previous={lang:state.lang,settings:state.settings};state.lang=lang;state.settings={...state.settings,mock:false,write_enabled:writable};shell();const clean=notice()===''&&!document.querySelector('#connection')&&!document.querySelector('.sidebar-bottom .live-dot');state.lang=previous.lang;state.settings=previous.settings;shell();return clean;},{lang,writable});assert(clean,'Live-device status must not appear in either language');checks++;}for(const width of [1440,390])for(const theme of ['light','dark']){await page.setViewportSize({width,height:1000});await page.evaluate(theme=>{localStorage.setItem('ff-theme',theme);document.documentElement.dataset.theme=theme;},theme);for(const name of ['dashboard','gallery','photo-sources','upload','templates','automation','playlists','history','settings']){await page.locator(`[data-page="${name}"]`).click();await page.waitForTimeout(350);if(name==='settings')await page.locator('#image-host-form').waitFor();const result=await page.evaluate(()=>{const children=[...document.querySelector('#main').children].filter(x=>x.getBoundingClientRect().height>0);return {overflow:document.documentElement.scrollWidth>innerWidth,buttonGaps:[...document.querySelectorAll('#main button')].flatMap(b=>{const next=b.nextElementSibling;if(next?.tagName!=='BUTTON')return [];const a=b.getBoundingClientRect(),c=next.getBoundingClientRect();if(!a.width||!c.width)return [];return [Math.abs(a.top-c.top)<4?c.left-a.right:c.top-a.bottom];}),gaps:children.slice(1).map((x,i)=>x.getBoundingClientRect().top-children[i].getBoundingClientRect().bottom)};});const controls=await page.evaluate(()=>{const nodes=[...document.querySelectorAll('#main input:not([type="checkbox"]):not([type="radio"]),#main select,#main textarea,#main button')].filter(x=>{const r=x.getBoundingClientRect();return r.width&&r.height&&getComputedStyle(x).visibility!=='hidden';});const issues=[];for(let i=0;i<nodes.length;i++)for(let j=i+1;j<nodes.length;j++){const a=nodes[i].getBoundingClientRect(),b=nodes[j].getBoundingClientRect();const ox=Math.min(a.right,b.right)-Math.max(a.left,b.left),oy=Math.min(a.bottom,b.bottom)-Math.max(a.top,b.top);const dy=Math.max(a.top,b.top)-Math.min(a.bottom,b.bottom),dx=Math.max(a.left,b.left)-Math.min(a.right,b.right);if((ox>Math.min(a.width,b.width)/2&&dy>=0&&dy<8)||(oy>Math.min(a.height,b.height)/2&&dx>=0&&dx<8))issues.push({a:nodes[i].id,b:nodes[j].id,gap:ox>0?dy:dx});}return issues;});assert(controls.length===0,`${name} ${width} ${theme} controls ${JSON.stringify(controls)}`);checks++;
 assert(result.buttonGaps.every(x=>x>=8),`${name} ${width} button gaps ${result.buttonGaps}`);assert(!result.overflow,`${name} ${width} overflow`);assert(result.gaps.every(x=>x>=16),`${name} ${width} gaps ${result.gaps}`);checks++;if(name==='templates'||name==='settings')await page.screenshot({path:`docs/screenshots/${name}-${width}-${theme}.png`,fullPage:true});}}
 await page.locator('[data-page="templates"]').click();await page.locator('[data-template="daily-poetry"]').click();await page.locator('#poem-choice').waitFor();assert(await page.locator('#poem-choice option').count()===21);checks++;await page.locator('#poem-choice').selectOption('jing-ye-si');await page.locator('#render-template').click();await page.locator('#template-image').waitFor();await page.waitForFunction(()=>document.querySelector('#template-image')?.naturalWidth===1200);checks++;await page.locator('#daily-poetry-job').click();assert(!await page.locator('#poetry-job-enabled').isChecked());checks++;const gap=await page.evaluate(()=>{const a=document.querySelector('#daily-poetry-job').getBoundingClientRect(),b=document.querySelector('#template-fields').getBoundingClientRect();return b.top-a.bottom;});assert(gap>=20,'Poetry action touches fields');checks++;await page.locator('#modal-cancel').click();await page.screenshot({path:'docs/screenshots/daily-poetry-controls-mobile-dark.png',fullPage:true});for(const width of [1440,390])for(const theme of ['light','dark']){await page.setViewportSize({width,height:1000});await page.evaluate(theme=>document.documentElement.dataset.theme=theme,theme);await page.locator('[data-page="templates"]').click();for(const id of ['calendar','daily-dashboard','daily-poetry','photo-text','quote','system-alert','weather']){await page.locator(`[data-template="${id}"]`).click();await page.waitForTimeout(250);await page.locator('#download-template').waitFor();if(id==='photo-text'){const photoGap=await page.evaluate(()=>document.querySelector('#template-photo-upload').getBoundingClientRect().top-document.querySelector('#field-photo_id').getBoundingClientRect().bottom);assert(photoGap>=12,`${width} ${theme} photo controls touch`);checks++;}const gap=await page.evaluate(()=>{const a=document.querySelector('#display-template').getBoundingClientRect(),b=document.querySelector('#download-template').getBoundingClientRect();return Math.abs(a.top-b.top)<4?b.left-a.right:b.top-a.bottom;});assert(gap>=8,`${id} ${width} preview buttons touch`);checks++;}for(const [name,button] of [['automation','new-job'],['playlists','new-playlist'],['templates','daily-poetry-job']]){await page.locator(`[data-page="${name}"]`).click();if(name==='templates'){await page.locator('[data-template="daily-poetry"]').click();await page.locator('#poem-choice').waitFor();}await page.locator('#'+button).click();const gap=await page.evaluate(()=>{const [a,b]=[...document.querySelectorAll('#modal .modal-actions button')].map(x=>x.getBoundingClientRect());return Math.abs(a.top-b.top)<4?b.left-a.right:b.top-a.bottom;});assert(gap>=8,`${name} ${width} modal buttons touch`);checks++;await page.locator('#modal-cancel').click();}}assert(unintended===0,`Cancel submitted ${unintended} requests`);checks++;await browser.close();console.log(`Layout/poetry browser: ${checks} passed (32 page/profile combinations)`);})().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-official-connection.cjs

@@ -1,3 +1,3 @@
 /* Local Mock only. No real official account or frame writes. */
 const assert=require('assert'),{chromium}=require('playwright');
-(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();const errors=[];let frameWrites=0;page.on('pageerror',e=>errors.push(e.message));await page.route('**/api/**',route=>{const r=route.request();if(r.method()!=='GET'&&!r.url().includes('/auth/')&&!r.url().endsWith('/official/connection')){frameWrites++;return route.abort();}return route.continue();});await page.goto('http://127.0.0.1:18787');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));await page.locator('[data-page="templates"]').click();await page.locator('.official-content-info summary').click();await page.waitForTimeout(300);if(await page.locator('#official-disconnect').count())await page.locator('#official-disconnect').click();await page.locator('#official-username').fill('mock-official-user');await page.locator('#official-password').fill('mock-password-not-saved');await page.locator('#official-login-form button').click();await page.locator('#official-device').waitFor();await page.locator('#official-select-form button').click();await page.locator('.official-account-panel').waitFor();await page.reload();await page.locator('.official-content-info summary').click();await page.locator('#official-disconnect').waitFor();assert((await page.locator('.official-account-panel').textContent()).includes('已关联画框'));for(const width of [1440,390]){await page.setViewportSize({width,height:1000});assert(!await page.evaluate(()=>document.documentElement.scrollWidth>innerWidth));}await page.locator('#official-disconnect').click();await page.locator('#official-login-form').waitFor();assert(await page.locator('#official-password').inputValue()==='');assert(!await page.evaluate(()=>JSON.stringify(localStorage).includes('mock-password-not-saved')));assert(errors.length===0&&frameWrites===0);await browser.close();console.log('Official connection UI: login, discover, select, reload, disconnect, 2 sizes PASS; 0 page errors, 0 frame writes');})().catch(e=>{console.error(e.message);process.exit(1)});
+(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();const errors=[];let frameWrites=0;page.on('pageerror',e=>errors.push(e.message));await page.route('**/api/**',route=>{const r=route.request();if(r.method()!=='GET'&&!r.url().includes('/auth/')&&!r.url().endsWith('/official/connection')){frameWrites++;return route.abort();}return route.continue();});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));await page.locator('[data-page="templates"]').click();await page.locator('.official-content-info summary').click();await page.waitForTimeout(300);if(await page.locator('#official-disconnect').count())await page.locator('#official-disconnect').click();await page.locator('#official-username').fill('mock-official-user');await page.locator('#official-password').fill('mock-password-not-saved');await page.locator('#official-login-form button').click();await page.locator('#official-device').waitFor();await page.locator('#official-select-form button').click();await page.locator('.official-account-panel').waitFor();await page.reload();await page.locator('.official-content-info summary').click();await page.locator('#official-disconnect').waitFor();assert((await page.locator('.official-account-panel').textContent()).includes('已关联画框'));for(const width of [1440,390]){await page.setViewportSize({width,height:1000});assert(!await page.evaluate(()=>document.documentElement.scrollWidth>innerWidth));}await page.locator('#official-disconnect').click();await page.locator('#official-login-form').waitFor();assert(await page.locator('#official-password').inputValue()==='');assert(!await page.evaluate(()=>JSON.stringify(localStorage).includes('mock-password-not-saved')));assert(errors.length===0&&frameWrites===0);await browser.close();console.log('Official connection UI: login, discover, select, reload, disconnect, 2 sizes PASS; 0 page errors, 0 frame writes');})().catch(e=>{console.error(e.message);process.exit(1)});

scripts/ui-photo-people.cjs

@@ -7,7 +7,7 @@ const assert=require('assert'),{chromium}=require('playwright');
  await page.route('**/api/v1/integrations/synology-photos',route=>route.fulfill({json:{configured:true,connected:true}}));
  await page.route('**/api/v1/integrations/synology-photos/people',route=>route.fulfill({json:[{id:1,name:'Family A',count:20,named:true},{id:2,name:'Family B',count:15,named:true},{id:3,name:'3',count:2,named:false}]}));
  try{
- await page.goto('http://127.0.0.1:18787');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));
+ 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="photo-sources"]').click();await page.locator('#add-photo-source').click();await page.locator('#source-id').fill(id);await page.locator('#source-name').fill('People fixture');await page.locator('#source-people-load').click();await page.locator('[data-person="1"]').waitFor();assert(await page.locator('[data-person]').count()===2);await page.locator('#people-unnamed').check();assert(await page.locator('[data-person]').count()===3);await page.locator('#people-search').fill('Family B');assert(await page.locator('[data-person]').count()===1);await page.locator('[data-person="2"]').check();await page.locator('#source-people-filter').check();await page.locator('#source-person-match').selectOption('all');assert(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));
  if(checks===0){await page.locator('#photo-source-form button[type="submit"]').click();await page.locator(`[data-source-edit="${id}"]`).waitFor();const saved=await page.evaluate(async id=>(await api('/api/v1/photo-sources')).find(s=>s.id===id),id);assert(saved.people_filter&&saved.person_match==='all'&&saved.person_ids.join(',')==='2');await page.locator(`[data-source-edit="${id}"]`).click();assert(await page.locator('#source-people-filter').isChecked());assert(await page.locator('#source-person-match').inputValue()==='all');}

scripts/ui-photo-retention.cjs

@@ -1,3 +1,3 @@
 /* Local mock server only; no vendor/cloud writes. PHOTO_ROOT must contain a fixture image. */
 const assert=require('assert'),{chromium}=require('playwright');
-(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();await page.goto('http://127.0.0.1:18787');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));const id='ui-photo-'+Date.now();let jobId;let checks=0;try{await page.locator('[data-page="photo-sources"]').click();await page.locator('#add-photo-source').click();await page.locator('#source-id').fill(id);await page.locator('#source-name').fill('UI photo fixture');await page.locator('#source-location').fill('.');await page.locator('#source-orientation').selectOption('landscape');await page.locator('#source-organized').check();await page.locator('#source-caption').check();await page.locator('#source-synology-previews').check();await page.locator('#photo-source-form button[type="submit"]').click();await page.locator(`[data-source-browse="${id}"]`).waitFor();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="photo-sources"]').click();await page.locator(`[data-source-browse="${id}"]`).click();await page.locator('[data-source-item]').first().waitFor();assert(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));await page.locator(`[data-source-edit="${id}"]`).click();assert(await page.locator('#source-id').inputValue()===id);assert(await page.locator('#source-orientation').inputValue()==='landscape');assert(await page.locator('#source-organized').isChecked());assert(await page.locator('#source-caption').isChecked());assert(await page.locator('#source-synology-previews').isChecked());await page.locator('#modal-cancel').click();checks++;}await page.locator(`[data-source-random="${id}"]`).click();await page.locator('#source-preview').waitFor();await page.waitForFunction(()=>document.querySelector('#source-preview')?.naturalWidth>0);assert(await page.locator('#source-preview').evaluate(img=>img.naturalWidth===1600&&img.naturalHeight===1200));const before=await page.evaluate(()=>api('/api/v1/devices/'+state.device));await page.locator('#modal-cancel').click();await page.locator(`[data-source-job="${id}"]`).click();assert(!await page.locator('#source-job-enabled').isChecked());await page.locator('#source-job-name').fill(id);await page.locator('#source-job-form button[type="submit"]').click();await page.locator('#new-job').waitFor();jobId=await page.evaluate(async id=>(await api('/api/v1/jobs')).find(j=>j.name===id).id,id);await page.evaluate(async jobId=>{const job=(await api('/api/v1/jobs')).find(j=>j.id===jobId);await jobEditor(job);},jobId);await page.locator('#job-photo-source').waitFor();assert(await page.locator('#job-form').textContent().then(x=>x.includes('最新成功图')||x.includes('latest confirmed')));assert(await page.locator('#job-content-type').inputValue()==='photo_source');assert(await page.locator('#job-photo-source').inputValue()===id);await page.locator('#modal-cancel').click();const after=await page.evaluate(()=>api('/api/v1/devices/'+state.device));assert(before.current_content.id===after.current_content.id);checks+=3;console.log('Photo sources browser: '+checks+' passed (8 language/size/theme profiles, preview and scheduler editing)');}finally{await page.evaluate(async({id,jobId})=>{if(jobId)await api('/api/v1/jobs/'+jobId,{method:'DELETE'});await api('/api/v1/photo-sources/'+id,{method:'DELETE'});},{id,jobId});await browser.close();}})().catch(e=>{console.error(e);process.exit(1)});
+(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();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));const id='ui-photo-'+Date.now();let jobId;let checks=0;try{await page.locator('[data-page="photo-sources"]').click();await page.locator('#add-photo-source').click();await page.locator('#source-id').fill(id);await page.locator('#source-name').fill('UI photo fixture');await page.locator('#source-location').fill('.');await page.locator('#source-orientation').selectOption('landscape');await page.locator('#source-organized').check();await page.locator('#source-caption').check();await page.locator('#source-synology-previews').check();await page.locator('#photo-source-form button[type="submit"]').click();await page.locator(`[data-source-browse="${id}"]`).waitFor();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="photo-sources"]').click();await page.locator(`[data-source-browse="${id}"]`).click();await page.locator('[data-source-item]').first().waitFor();assert(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));await page.locator(`[data-source-edit="${id}"]`).click();assert(await page.locator('#source-id').inputValue()===id);assert(await page.locator('#source-orientation').inputValue()==='landscape');assert(await page.locator('#source-organized').isChecked());assert(await page.locator('#source-caption').isChecked());assert(await page.locator('#source-synology-previews').isChecked());await page.locator('#modal-cancel').click();checks++;}await page.locator(`[data-source-random="${id}"]`).click();await page.locator('#source-preview').waitFor();await page.waitForFunction(()=>document.querySelector('#source-preview')?.naturalWidth>0);assert(await page.locator('#source-preview').evaluate(img=>img.naturalWidth===1600&&img.naturalHeight===1200));const before=await page.evaluate(()=>api('/api/v1/devices/'+state.device));await page.locator('#modal-cancel').click();await page.locator(`[data-source-job="${id}"]`).click();assert(!await page.locator('#source-job-enabled').isChecked());await page.locator('#source-job-name').fill(id);await page.locator('#source-job-form button[type="submit"]').click();await page.locator('#new-job').waitFor();jobId=await page.evaluate(async id=>(await api('/api/v1/jobs')).find(j=>j.name===id).id,id);await page.evaluate(async jobId=>{const job=(await api('/api/v1/jobs')).find(j=>j.id===jobId);await jobEditor(job);},jobId);await page.locator('#job-photo-source').waitFor();assert(await page.locator('#job-form').textContent().then(x=>x.includes('最新成功图')||x.includes('latest confirmed')));assert(await page.locator('#job-content-type').inputValue()==='photo_source');assert(await page.locator('#job-photo-source').inputValue()===id);await page.locator('#modal-cancel').click();const after=await page.evaluate(()=>api('/api/v1/devices/'+state.device));assert(before.current_content.id===after.current_content.id);checks+=3;console.log('Photo sources browser: '+checks+' passed (8 language/size/theme profiles, preview and scheduler editing)');}finally{await page.evaluate(async({id,jobId})=>{if(jobId)await api('/api/v1/jobs/'+jobId,{method:'DELETE'});await api('/api/v1/photo-sources/'+id,{method:'DELETE'});},{id,jobId});await browser.close();}})().catch(e=>{console.error(e);process.exit(1)});

scripts/ui-photo-sources.cjs

@@ -1,3 +1,3 @@
 /* Local mock server only; no vendor/cloud writes. PHOTO_ROOT must contain a fixture image. */
 const assert=require('assert'),{chromium}=require('playwright');
-(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();await page.goto('http://127.0.0.1:18787');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));const id='ui-photo-'+Date.now();let jobId;let checks=0;try{await page.locator('[data-page="photo-sources"]').click();await page.locator('#add-photo-source').click();await page.locator('#source-id').fill(id);await page.locator('#source-name').fill('UI photo fixture');await page.locator('#source-location').fill('.');await page.locator('#source-orientation').selectOption('landscape');await page.locator('#source-organized').check();await page.locator('#source-caption').check();await page.locator('#source-synology-previews').check();await page.locator('#photo-source-form button[type="submit"]').click();await page.locator(`[data-source-browse="${id}"]`).waitFor();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="photo-sources"]').click();await page.locator(`[data-source-browse="${id}"]`).click();await page.locator('[data-source-item]').first().waitFor();assert(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));await page.locator(`[data-source-edit="${id}"]`).click();assert(await page.locator('#source-id').inputValue()===id);assert(await page.locator('#source-orientation').inputValue()==='landscape');assert(await page.locator('#source-organized').isChecked());assert(await page.locator('#source-caption').isChecked());assert(await page.locator('#source-synology-previews').isChecked());await page.locator('#modal-cancel').click();checks++;}await page.locator(`[data-source-random="${id}"]`).click();await page.locator('#source-preview').waitFor();await page.waitForFunction(()=>document.querySelector('#source-preview')?.naturalWidth>0);assert(await page.locator('#source-preview').evaluate(img=>img.naturalWidth===1600&&img.naturalHeight===1200));const before=await page.evaluate(()=>api('/api/v1/devices/'+state.device));await page.locator('#modal-cancel').click();await page.locator(`[data-source-job="${id}"]`).click();assert(!await page.locator('#source-job-enabled').isChecked());await page.locator('#source-job-name').fill(id);await page.locator('#source-job-form button[type="submit"]').click();await page.locator('#new-job').waitFor();jobId=await page.evaluate(async id=>(await api('/api/v1/jobs')).find(j=>j.name===id).id,id);await page.evaluate(async jobId=>{const job=(await api('/api/v1/jobs')).find(j=>j.id===jobId);await jobEditor(job);},jobId);await page.locator('#job-photo-source').waitFor();assert(await page.locator('#job-content-type').inputValue()==='photo_source');assert(await page.locator('#job-photo-source').inputValue()===id);await page.locator('#modal-cancel').click();const after=await page.evaluate(()=>api('/api/v1/devices/'+state.device));assert(before.current_content.id===after.current_content.id);checks+=3;console.log('Photo sources browser: '+checks+' passed (8 language/size/theme profiles, preview and scheduler editing)');}finally{await page.evaluate(async({id,jobId})=>{if(jobId)await api('/api/v1/jobs/'+jobId,{method:'DELETE'});await api('/api/v1/photo-sources/'+id,{method:'DELETE'});},{id,jobId});await browser.close();}})().catch(e=>{console.error(e);process.exit(1)});
+(async()=>{const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});const page=await browser.newPage();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));const id='ui-photo-'+Date.now();let jobId;let checks=0;try{await page.locator('[data-page="photo-sources"]').click();await page.locator('#add-photo-source').click();await page.locator('#source-id').fill(id);await page.locator('#source-name').fill('UI photo fixture');await page.locator('#source-location').fill('.');await page.locator('#source-orientation').selectOption('landscape');await page.locator('#source-organized').check();await page.locator('#source-caption').check();await page.locator('#source-synology-previews').check();await page.locator('#photo-source-form button[type="submit"]').click();await page.locator(`[data-source-browse="${id}"]`).waitFor();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="photo-sources"]').click();await page.locator(`[data-source-browse="${id}"]`).click();await page.locator('[data-source-item]').first().waitFor();assert(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));await page.locator(`[data-source-edit="${id}"]`).click();assert(await page.locator('#source-id').inputValue()===id);assert(await page.locator('#source-orientation').inputValue()==='landscape');assert(await page.locator('#source-organized').isChecked());assert(await page.locator('#source-caption').isChecked());assert(await page.locator('#source-synology-previews').isChecked());await page.locator('#modal-cancel').click();checks++;}await page.locator(`[data-source-random="${id}"]`).click();await page.locator('#source-preview').waitFor();await page.waitForFunction(()=>document.querySelector('#source-preview')?.naturalWidth>0);assert(await page.locator('#source-preview').evaluate(img=>img.naturalWidth===1600&&img.naturalHeight===1200));const before=await page.evaluate(()=>api('/api/v1/devices/'+state.device));await page.locator('#modal-cancel').click();await page.locator(`[data-source-job="${id}"]`).click();assert(!await page.locator('#source-job-enabled').isChecked());await page.locator('#source-job-name').fill(id);await page.locator('#source-job-form button[type="submit"]').click();await page.locator('#new-job').waitFor();jobId=await page.evaluate(async id=>(await api('/api/v1/jobs')).find(j=>j.name===id).id,id);await page.evaluate(async jobId=>{const job=(await api('/api/v1/jobs')).find(j=>j.id===jobId);await jobEditor(job);},jobId);await page.locator('#job-photo-source').waitFor();assert(await page.locator('#job-content-type').inputValue()==='photo_source');assert(await page.locator('#job-photo-source').inputValue()===id);await page.locator('#modal-cancel').click();const after=await page.evaluate(()=>api('/api/v1/devices/'+state.device));assert(before.current_content.id===after.current_content.id);checks+=3;console.log('Photo sources browser: '+checks+' passed (8 language/size/theme profiles, preview and scheduler editing)');}finally{await page.evaluate(async({id,jobId})=>{if(jobId)await api('/api/v1/jobs/'+jobId,{method:'DELETE'});await api('/api/v1/photo-sources/'+id,{method:'DELETE'});},{id,jobId});await browser.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

@@ -0,0 +1,54 @@
+/* Mock-only: known image metadata renders real slots; no synthetic skeletons. */
+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 browser=await chromium.launch({headless:true,executablePath:process.env.CHROME_EXECUTABLE||'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});
+ try{
+  const page=await browser.newPage();const errors=[];page.on('pageerror',e=>errors.push(e.message));
+  let releaseAccount;await page.route('**/api/v1/auth/me',async r=>{await new Promise(resolve=>releaseAccount=resolve);await r.continue();});
+  await page.goto(base);await page.locator('#nav button').first().waitFor();assert.equal(await page.locator('.image-pending,.placeholder-line,.page-placeholder').count(),0);assert.equal(await page.locator('.page-loading').count(),0);releaseAccount();
+  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();
+  let checks=1;
+  for(const width of [1440,390]){
+   await page.setViewportSize({width,height:844});await page.evaluate(()=>state.galleryCache?.clear());let releaseMetadata,metadataRequested,releaseImage,imageRequested;
+   await page.route('**/api/v1/devices/*/images',async r=>{metadataRequested();await new Promise(resolve=>releaseMetadata=resolve);await r.fulfill({json:[{image_id:1,name:'Progressive fixture',url:'/progressive-fixture.svg',current:false}]});});
+   await page.route('**/progressive-fixture.svg*',async r=>{assert.equal(await page.locator('#gallery-search').count(),1,'Search must precede image requests');assert(await page.locator('#gallery-search').evaluate(e=>typeof e.oninput==='function'));imageRequested();await new Promise(resolve=>releaseImage=resolve);await r.fulfill({contentType:'image/svg+xml',body:'<svg xmlns="http://www.w3.org/2000/svg" width="300" height="400"/>'});});
+   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.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'));
+   const cachedMetadata=new Promise(resolve=>metadataRequested=resolve);const cachedImage=new Promise(resolve=>imageRequested=resolve);
+   await page.evaluate(()=>{window.navigation=navigate('gallery');});await cachedMetadata;await cachedImage;
+   assert.equal(await page.locator('#gallery-search').count(),1,'Search must exist while cached metadata refresh is pending');assert(await page.locator('#gallery-search').evaluate(e=>typeof e.oninput==='function'),'Search must be interactive');assert.equal(await page.locator('.image-card').count(),1);assert.equal(await page.locator('.image-loading .spinner').count(),1);assert.equal(await page.locator('.image-pending,.placeholder-line,.page-placeholder').count(),0);checks++;
+   releaseMetadata();await page.evaluate(()=>window.navigation);releaseImage();await page.waitForFunction(()=>document.querySelector('.thumb')?.naturalWidth===300&&!document.querySelector('.image-loading'));
+
+   await page.unroute('**/api/v1/devices/*/images');await page.unroute('**/progressive-fixture.svg*');
+   let releaseDevice,deviceRequested;await page.route('**/api/v1/devices/living-room',async r=>{deviceRequested();await new Promise(resolve=>releaseDevice=resolve);await r.continue();});
+   const device=new Promise(resolve=>deviceRequested=resolve);await page.evaluate(()=>{window.navigation=navigate('dashboard');});await device;
+   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"/>'}));
+  const jobs=new Promise(resolve=>jobsRequested=resolve);await page.evaluate(()=>{state.tab='local';return navigate('gallery');});await jobs;
+  assert.equal(await page.locator('.asset-select').count(),1);assert(await page.locator('#gallery-search').evaluate(e=>typeof e.oninput==='function'));await page.locator('#gallery-search').fill('no-match');assert(await page.locator('.image-card').evaluate(e=>e.hidden));releaseJobs();checks++;
+  assert.deepEqual(errors,[]);console.log('Known image positions without skeletons:',checks,'checks PASS; delayed bootstrap, metadata and images; no page errors');
+ }finally{await browser.close();}
+})().catch(e=>{console.error(e.message);process.exit(1)});

scripts/ui-smoke.cjs

@@ -2,7 +2,7 @@
 const fs=require('fs');const path=require('path');const assert=require('assert');const {chromium}=require('playwright');
 (async()=>{
  const uploadName='browser-upload-'+Date.now();const root=path.resolve(__dirname,'..');const env=fs.readFileSync(process.env.FRAME_FLOW_ENV_FILE||path.join(root,'.env'),'utf8');const token=env.split('\n').find(x=>x.startsWith('FRAME_FLOW_TOKEN=')).slice('FRAME_FLOW_TOKEN='.length);
- const base=process.env.FRAME_FLOW_URL||'http://127.0.0.1:18787';const response=await fetch(base+'/api/v1/settings',{headers:{Authorization:'Bearer '+token}});const settings=await response.json();assert(settings.mock===true,'UI smoke requires Mock mode');
+ const base=process.env.FRAME_FLOW_URL||'http://127.0.0.1:6005';const response=await fetch(base+'/api/v1/settings',{headers:{Authorization:'Bearer '+token}});const settings=await response.json();assert(settings.mock===true,'UI smoke requires Mock mode');
  const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});
  const context=await browser.newContext({viewport:{width:1440,height:1000}});const page=await context.newPage();const errors=[];page.on('pageerror',e=>errors.push(e.message.replaceAll(token,'[REDACTED]')));let checks=0;
  await page.addInitScript(()=>Object.defineProperty(window.crypto,'randomUUID',{value:undefined,configurable:true}));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();assert(await page.locator('h2').first().innerText()==='客厅相框');checks++;

scripts/ui-studio-image-loading.cjs

@@ -0,0 +1,32 @@
+/* Mock-only editor regression: parallel image requests, stable regions and live 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 browser=await chromium.launch({headless:true,executablePath:process.env.CHROME_EXECUTABLE||'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});
+ try{
+  const page=await browser.newPage();const errors=[];page.on('pageerror',e=>errors.push(e.message));
+  await page.route('**/api/v1/assets?*',r=>r.fulfill({json:[{asset_id:'studio-fixture-a',name:'A'},{asset_id:'studio-fixture-b',name:'B'}]}));
+  await page.route('**/api/v1/layout/plan',r=>r.fulfill({json:{width:1200,height:1600,regions:[{asset_id:'studio-fixture-a',x:20,y:200,width:550,height:900},{asset_id:'studio-fixture-b',x:620,y:200,width:550,height:900}]}}));
+  let requests,releases,failSecond=false;
+  await page.route('**/api/v1/assets/studio-fixture-*',async r=>{const key=r.request().url().split('-').pop();requests.add(key);await new Promise(resolve=>releases[key]=resolve);await r.fulfill({contentType:'image/svg+xml',body:failSecond&&key==='b'?'invalid image':'<svg xmlns="http://www.w3.org/2000/svg" width="300" height="400"><rect width="300" height="400" fill="#167253"/></svg>'});});
+  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();let checks=0;
+  for(const width of [1440,390])for(const theme of ['light','dark']){
+   requests=new Set();releases={};await page.setViewportSize({width,height:900});await page.evaluate(theme=>{document.documentElement.dataset.theme=theme;return navigate('studio');},theme);await page.locator('.manual-collage summary').click();
+   await page.locator('#studio-assets input').nth(0).check();await page.locator('#studio-assets input').nth(1).check();await page.locator('#studio-plan').click();
+   await page.waitForFunction(()=>document.querySelectorAll('.studio-region .spinner').length===2);for(let n=0;n<100&&requests.size<2;n++)await page.waitForTimeout(20);assert.equal(requests.size,2,'Both requests must start before either finishes');assert(await page.locator('#studio-render').isEnabled());checks++;
+   assert(await page.locator('.studio-region').evaluateAll(regions=>regions.every(region=>{const a=region.getBoundingClientRect(),b=region.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++;
+   const field=page.locator('[data-region="0"][data-key="x"]');await field.fill('40');await field.dispatchEvent('input');assert(await page.locator('.studio-region').first().evaluate(e=>Math.abs(parseFloat(e.style.left)-40/1200*100)<0.01));checks++;
+   const before=await page.locator('.studio-region').nth(1).boundingBox();releases.b();await page.waitForFunction(()=>document.querySelectorAll('.studio-region')[1].querySelector('img').naturalWidth===300&&!document.querySelectorAll('.studio-region')[1].querySelector('.image-loading'));
+   assert.equal(await page.locator('.studio-region').first().locator('.spinner').count(),1);assert.deepEqual(await page.locator('.studio-region').nth(1).boundingBox(),before);checks++;
+   const region=page.locator('.studio-region').nth(1);await region.scrollIntoViewIfNeeded();const point=await region.boundingBox();const old=await page.locator('[data-region="1"][data-key="x"]').inputValue();await page.mouse.move(point.x+point.width/2,point.y+Math.min(point.height/2,80));await page.mouse.down();await page.mouse.move(point.x+point.width/2-10,point.y+Math.min(point.height/2,80)+5,{steps:3});await page.mouse.up();assert.notEqual(await page.locator('[data-region="1"][data-key="x"]').inputValue(),old);checks++;
+   releases.a();await page.waitForFunction(()=>document.querySelectorAll('.studio-region img').length===2&&[...document.querySelectorAll('.studio-region img')].every(img=>img.naturalWidth===300)&&!document.querySelector('.studio-region .image-loading'));checks++;
+   assert(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth));checks++;
+  }
+  requests=new Set();releases={};failSecond=true;await page.locator('#studio-plan').click();for(let n=0;n<100&&requests.size<2;n++)await page.waitForTimeout(20);assert.equal(requests.size,2);
+  releases.b();await page.locator('.studio-region .image-load-error').waitFor();assert.equal(await page.locator('.studio-region').first().locator('.spinner').count(),1);assert(await page.locator('#studio-render').isEnabled());checks++;
+  const errorField=page.locator('[data-region="1"][data-key="x"]');await errorField.fill('600');await errorField.dispatchEvent('input');assert.equal(await page.locator('.studio-region').nth(1).evaluate(e=>e.style.left),'50%');checks++;
+  releases.a();await page.waitForFunction(()=>document.querySelector('.studio-region img')?.naturalWidth===300);assert.equal(await page.locator('.studio-region .spinner').count(),0);checks++;
+  assert.deepEqual(errors,[]);console.log('Studio image loading:',checks,'checks PASS; parallel requests, independent completion, local spinners, coordinate editing and dragging; no page errors');
+ }finally{await browser.close();}
+})().catch(e=>{console.error(e.message);process.exit(1)});

scripts/ui-widgets.cjs

@@ -4,7 +4,7 @@ const assert=require('assert'),{chromium}=require('playwright');
  const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});
  const page=await browser.newPage();const errors=[];page.on('pageerror',e=>errors.push(e.message));let status='AUTH_REQUIRED',checks=0;
  await page.route('**/api/v1/devices/*/widgets',route=>route.fulfill({json:{source:status==='AUTH_REQUIRED'?'snapshot':'live',configured:status!=='AUTH_REQUIRED',status,observed_at:'2026-10-02',catalog:[],current:null,current_verified:status==='NO_WIDGET',writable:false}}));
- await page.goto('http://127.0.0.1:18787');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();
+ 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();
  for(const lang of ['zh','en'])for(const value of ['AUTH_REQUIRED','NO_WIDGET','CURRENT_UNVERIFIED']){
   status=value;await page.evaluate(lang=>{state.lang=lang;return navigate('templates');},lang);
   await page.locator('.widget-auth-notice').waitFor({state:'attached'});

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

@@ -613,6 +613,16 @@
   },
   "Operation": {
     "properties": {
+      "recovery": {
+        "anyOf": [
+          {
+            "$ref": "#/components/schemas/RecoveryState"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
       "operation_id": {
         "type": "string",
         "title": "Operation Id"
@@ -859,6 +869,7 @@
         "type": "string",
         "enum": [
           "local",
+          "synology-photos",
           "webdav",
           "google-drive",
           "alipan",
@@ -1011,6 +1022,7 @@
         "type": "string",
         "enum": [
           "local",
+          "synology-photos",
           "webdav",
           "google-drive",
           "alipan",
@@ -1422,5 +1434,48 @@
       "type"
     ],
     "title": "AutoCollageContent"
+  },
+  "RecoveryState": {
+    "properties": {
+      "state": {
+        "type": "string",
+        "enum": [
+          "checking",
+          "manual_review",
+          "resolved"
+        ],
+        "title": "State"
+      },
+      "reason": {
+        "type": "string",
+        "title": "Reason"
+      },
+      "first_checked_at": {
+        "type": "string",
+        "title": "First Checked At"
+      },
+      "last_checked_at": {
+        "type": "string",
+        "title": "Last Checked At"
+      },
+      "checks": {
+        "type": "integer",
+        "title": "Checks"
+      },
+      "requires_manual_review": {
+        "type": "boolean",
+        "title": "Requires Manual Review"
+      }
+    },
+    "type": "object",
+    "required": [
+      "state",
+      "reason",
+      "first_checked_at",
+      "last_checked_at",
+      "checks",
+      "requires_manual_review"
+    ],
+    "title": "RecoveryState"
   }
 }

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):
@@ -423,3 +424,35 @@ def test_scoped_client_operation_isolation(client, service):
     assert [op["operation_id"] for op in client.get("/api/v1/operations").json()] == [
         own
     ]
+
+
+def test_settings_exposes_storage_display_name(client, service):
+    service.settings.storage_name = "Family NAS"
+    result = client.get("/api/v1/settings").json()
+    assert result["storage_name"] == "Family NAS"
+    destinations = {d["id"]: d for d in result["gallery_destinations"]}
+    assert set(destinations) == {"cloud", "local"}
+    assert destinations["cloud"]["name"] == "KoKonna"
+    assert destinations["local"]["name"] == "Family NAS"
+    assert all(d["connected"] and d["supports_upload"] for d in destinations.values())
+    assert "test-frame-token" not in str(result)
+
+
+def test_storage_display_name_environment(monkeypatch):
+    monkeypatch.setenv("FRAME_FLOW_STORAGE_NAME", "  Family NAS  ")
+    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

@@ -1,3 +1,4 @@
+from types import SimpleNamespace
 from unittest.mock import Mock
 
 import pytest
@@ -7,11 +8,28 @@ from pigway_frame_flow.drivers.kokonna.client import KokonnaClient
 from pigway_frame_flow.errors import FlowError
 
 
+@pytest.fixture(autouse=True)
+def transport_clock(monkeypatch):
+    import pigway_frame_flow.drivers.kokonna.client as module
+
+    clock = SimpleNamespace(now=0.0, waits=[])
+
+    def sleep(seconds):
+        clock.waits.append(seconds)
+        clock.now += seconds
+
+    monkeypatch.setattr(
+        module, "time", SimpleNamespace(monotonic=lambda: clock.now, sleep=sleep)
+    )
+    return clock
+
+
 def session(body=None, status=200):
     s = Mock()
     s.request.return_value.status_code = status
     s.request.return_value.json.return_value = body or {}
     s.request.return_value.content = b"image"
+    s.request.return_value.headers = {}
     return s
 
 
@@ -88,7 +106,7 @@ def test_timeout_redaction_no_retry(write):
         c.display(1) if write else c.get_device()
     assert "secret" not in str(e.value)
     assert e.value.code == ("WRITE_RESULT_UNKNOWN" if write else "CLOUD_UNAVAILABLE")
-    assert s.request.call_count == 1
+    assert s.request.call_count == (1 if write else 3)
 
 
 @pytest.mark.parametrize("status", [401, 429, 500, 530])
@@ -109,12 +127,204 @@ def test_invalid_upload_id(tmp_path):
     assert e.value.code == "WRITE_RESULT_UNKNOWN"
 
 
-def test_rate_budget():
+def test_rate_budget(transport_clock):
     s = session({"nickname": "x"})
     c = KokonnaClient("secret", session=s)
     for _ in range(18):
         c.get_device()
-    with pytest.raises(FlowError) as e:
+    c.get_device()
-        c.get_device()
+    assert s.request.call_count == 19
-    assert e.value.code == "RATE_LIMITED"
+    assert transport_clock.waits == [60]
-    assert s.request.call_count == 18
+
+
+@pytest.mark.parametrize(
+    "exception,category",
+    [
+        (requests.ConnectTimeout, "connect_timeout"),
+        (requests.ReadTimeout, "read_timeout"),
+        (requests.exceptions.SSLError, "tls_error"),
+        (requests.ConnectionError, "connection_error"),
+        (requests.Timeout, "timeout"),
+        (requests.RequestException, "request_error"),
+    ],
+)
+def test_transport_failure_records_safe_category_without_replay(exception, category):
+    s = session()
+    s.request.side_effect = exception("secret https://host/secret")
+    c = KokonnaClient("secret", True, s)
+    with pytest.raises(FlowError) as error:
+        c.display(1)
+    assert error.value.code == (
+        "CLOUD_UNAVAILABLE" if category == "connect_timeout" else "WRITE_RESULT_UNKNOWN"
+    )
+    assert error.value.details["transport_error"] == category
+    assert error.value.details["attempts"] == (
+        3 if category == "connect_timeout" else 1
+    )
+    assert "secret" not in str(error.value.details)
+    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})
+    response = s.request.return_value
+    s.request.side_effect = [requests.ConnectTimeout("private"), response]
+    c = KokonnaClient("private", True, s)
+    c.display(1) if write else c.get_device()
+    assert s.request.call_count == 2
+    assert transport_clock.waits == [1]
+
+
+@pytest.mark.parametrize(
+    "message,code,kind",
+    [
+        ("image not found", "NOT_FOUND", "image_not_found"),
+        ("imageId is empty", "INVALID_REQUEST", "invalid_image_id"),
+        ("can not find robot private", "CONFIG_REQUIRED", "device_key_invalid"),
+    ],
+)
+def test_documented_500_rejection_does_not_lock_or_retry(message, code, kind):
+    s = session({"message": message}, 500)
+    c = KokonnaClient("private", True, s)
+    with pytest.raises(FlowError) as error:
+        c.display(1)
+    assert error.value.code == code
+    assert error.value.details["write_outcome"] == "rejected"
+    assert error.value.details["failure_kind"] == kind
+    assert "private" not in str(error.value.details)
+    assert s.request.call_count == 1
+
+
+@pytest.mark.parametrize("status", [500, 502, 503, 530])
+def test_generic_5xx_read_retries_but_write_never_replays(status):
+    for write in [False, True]:
+        s = session({"message": "unknown failure private"}, status)
+        c = KokonnaClient("private", True, s)
+        with pytest.raises(FlowError) as error:
+            c.display(1) if write else c.get_device()
+        assert s.request.call_count == (1 if write else 3)
+        assert error.value.code == (
+            "WRITE_RESULT_UNKNOWN" if write else "CLOUD_UNAVAILABLE"
+        )
+        assert "private" not in str(error.value.details)
+
+
+def test_rate_limit_honors_retry_after_and_closes_response(transport_clock):
+    s = session({"message": "rate limited"}, 429)
+    first = s.request.return_value
+    first.headers = {"Retry-After": "7"}
+    second = session({"success": True}).request.return_value
+    s.request.side_effect = [first, second]
+    KokonnaClient("private", True, s).display(1)
+    assert s.request.call_count == 2
+    assert transport_clock.waits == [7]
+    first.close.assert_called_once()
+    second.close.assert_called_once()
+
+
+def test_long_retry_after_preserves_cooldown_without_early_request(transport_clock):
+    s = session({"message": "rate limited"}, 429)
+    s.request.return_value.headers = {"Retry-After": "120"}
+    c = KokonnaClient("private", True, s)
+    for _ in range(2):
+        with pytest.raises(FlowError) as error:
+            c.display(1)
+        assert error.value.code == "RATE_LIMITED"
+    assert s.request.call_count == 1
+    assert transport_clock.waits == []
+
+
+@pytest.mark.parametrize("header", [None, "bad", "nan", "inf"])
+def test_invalid_retry_after_defaults_to_one_minute(header):
+    from pigway_frame_flow.drivers.kokonna.client import SafeTransport
+
+    assert SafeTransport._retry_after(header) == 60
+
+
+def test_retry_after_accepts_http_date():
+    from datetime import UTC, datetime, timedelta
+    from email.utils import format_datetime
+
+    from pigway_frame_flow.drivers.kokonna.client import SafeTransport
+
+    future = format_datetime(datetime.now(UTC) + timedelta(seconds=30), usegmt=True)
+    assert 28 <= SafeTransport._retry_after(future) <= 30
+
+
+def test_invalid_write_response_is_never_retried():
+    s = session({"success": False, "message": "private"})
+    with pytest.raises(FlowError) as error:
+        KokonnaClient("private", True, s).display(1)
+    assert error.value.code == "WRITE_RESULT_UNKNOWN"
+    assert error.value.details["failure_kind"] == "invalid_response"
+    assert s.request.call_count == 1
+
+
+@pytest.mark.parametrize(
+    "failure,expected",
+    [
+        ("connect_timeout", "CLOUD_UNAVAILABLE"),
+        ("business_rejection", "CONFIG_REQUIRED"),
+        ("rate_limit", "RATE_LIMITED"),
+    ],
+)
+def test_proven_upload_failures_end_failed_without_device_lock(
+    service, monkeypatch, failure, expected
+):
+    from test_display import submit
+
+    s = session({"message": "can not find robot private"}, 500)
+    if failure == "rate_limit":
+        s.request.return_value.status_code = 429
+    if failure == "connect_timeout":
+        s.request.side_effect = requests.ConnectTimeout("private")
+    c = KokonnaClient("private", True, s)
+    monkeypatch.setattr(service.registry.get("living-room"), "upload", c.upload)
+    operation = submit(service)
+    service.process_one()
+    op = service.operation(operation)
+    assert op["status"] == "FAILED"
+    assert op["error"]["code"] == expected
+    assert not service.blocked("living-room")
+
+
+@pytest.mark.parametrize("value", [True, False, 0, -1, "12", None])
+def test_invalid_upload_id_never_becomes_confirmed(tmp_path, value):
+    path = tmp_path / "image.jpg"
+    path.write_bytes(b"jpeg")
+    s = session({"id": value})
+    with pytest.raises(FlowError) as error:
+        KokonnaClient("private", True, s).upload(path, "image.jpg")
+    assert error.value.code == "WRITE_RESULT_UNKNOWN"
+    assert s.request.call_count == 1
+
+
+def test_ambiguous_failure_after_safe_rejection_stops_retrying(transport_clock):
+    s = session({"message": "limited"}, 429)
+    first = s.request.return_value
+    first.headers = {"Retry-After": "1"}
+    s.request.side_effect = [first, requests.ReadTimeout("private")]
+    with pytest.raises(FlowError) as error:
+        KokonnaClient("private", True, s).display(1)
+    assert error.value.code == "WRITE_RESULT_UNKNOWN"
+    assert error.value.details["attempts"] == 2
+    assert s.request.call_count == 2
+    assert transport_clock.waits == [1]

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"
+    assert service.operation(first)["status"] == "UNKNOWN"
-    with pytest.raises(FlowError):
+    second = submit(service, priority=10)
-        submit(service)
+    assert second != first
-    assert service.process_one() is False
+    assert service.process_one()
-    assert service.reconcile(id)["resolved"] is False
+    assert service.operation(first)["status"] == "FAILED"
-    assert service.reconcile(id, True)["resolved"] is True
+    assert service.operation(second)["status"] == "UNKNOWN"
-    assert service.operation(id)["status"] == "FAILED"
+    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):
@@ -152,3 +253,55 @@ def test_offline(service):
     id = submit(service)
     service.process_one()
     assert service.operation(id)["error"]["code"] == "DEVICE_OFFLINE"
+
+
+def test_late_sync_resolves_unknown_without_upload_retry(service, monkeypatch):
+    id = submit(service)
+    service.process_one()
+    service.update(id, "UNKNOWN")
+    driver = service.registry.get("living-room")
+    calls = []
+    device = driver.device
+    monkeypatch.setattr(driver, "device", lambda **kw: calls.append(kw) or device(**kw))
+    service.sync()
+    assert service.operation(id)["status"] == "COMPLETED"
+    assert driver.client.uploads == 1
+    assert calls == [{"refresh": True}]
+    assert not service.blocked("living-room")
+    assert service.db.one(
+        "SELECT confirmed_at FROM managed_cloud_uploads WHERE operation_id=?", (id,)
+    )["confirmed_at"]
+
+
+def test_unknown_wrong_target_stays_locked_and_queries_at_most_once_per_minute(
+    service, monkeypatch
+):
+    id = submit(service)
+    service.process_one()
+    service.update(id, "UNKNOWN")
+    driver = service.registry.get("living-room")
+    driver.client.display(1)
+    driver.invalidate()
+    calls = []
+    device = driver.device
+    monkeypatch.setattr(driver, "device", lambda **kw: calls.append(kw) or device(**kw))
+    service.sync()
+    service.sync()
+    assert service.operation(id)["status"] == "UNKNOWN"
+    assert service.blocked("living-room")
+    assert driver.client.uploads == 1
+    assert len(calls) == 1
+
+
+def test_unknown_matching_image_without_sync_stays_locked(service, monkeypatch):
+    id = submit(service)
+    service.process_one()
+    service.update(id, "UNKNOWN")
+    driver = service.registry.get("living-room")
+    device = driver.device()
+    device.current_content.synced = False
+    monkeypatch.setattr(driver, "device", lambda **kw: device)
+    service.sync()
+    assert service.operation(id)["status"] == "UNKNOWN"
+    assert service.blocked("living-room")
+    assert driver.client.uploads == 1

tests/test_extensions.py

@@ -373,3 +373,30 @@ def test_ai_layout_sends_metadata_only_and_validates_response(
     assert b"test-ai-secret" not in calls[0]["body"]
     assert image.getvalue() not in calls[0]["body"]
     assert calls[0]["headers"]["Authorization"] == "Bearer test-ai-secret"
+
+
+def test_webhook_matching_event_after_unrelated_backlog(client, service, monkeypatch):
+    import json
+
+    service.settings.image_url_hosts.append("example.com")
+    response = client.post(
+        "/api/v1/webhooks",
+        json={
+            "callback_url": "https://example.com/events",
+            "event_types": ["operation.failed"],
+        },
+    )
+    assert response.status_code == 201
+    for _ in range(500):
+        service.db.event("display.changed", {})
+    service.db.event("operation.failed", {"operation_id": "expected"})
+    sent = []
+    monkeypatch.setattr(
+        service.assets, "fetch_url", lambda url, **kwargs: sent.append(kwargs) or b""
+    )
+    service.webhooks.tick()
+    service.webhooks.last = 0
+    service.webhooks.tick()
+    assert len(sent) == 1
+    assert json.loads(sent[0]["body"])["data"] == {"operation_id": "expected"}
+    assert len(service.db.all("SELECT * FROM webhook_deliveries")) == 1

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_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"))