Skip to content

chore: release 1.0.0-rc.1 - #34

Merged
ant1fr merged 110 commits into
mainfrom
develop
Nov 19, 2026
Merged

ant1fr merged 110 commits into
mainfrom
develop

Conversation

@ant1fr

@ant1fr ant1fr commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Summary

First release candidate of Smart Frame Engine: merges develop into main.

  • Web UI (dashboard, playground, settings), admin login, ambient context, Zeroconf
  • Music album dedup, mobile overflow fix
  • Release pipeline (multi-arch GHCR image, Trivy, GitHub Release notes), CodeQL, Dependabot
  • Production compose files, new README, wiki, community files

After merge

Tag v1.0.0-rc.1 on main to run the release workflow (pre-release: only the exact tag is pushed, latest is untouched). Then set the GHCR package visibility to Public.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq

ant1fr and others added 30 commits November 14, 2026 17:16
Python 3.11+ package with FastAPI, Pydantic v2, httpx, Pillow, NumPy and
APScheduler. Ruff, mypy (strict) and pytest are configured in pyproject.toml.
Providers, processor and clients packages are created as documented
placeholders for upcoming milestones.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EnvSettings holds infrastructure settings (data dir, API key, proxy, CORS,
limits) and optional runtime seeds read from .env. RuntimeConfig groups the
UI-editable sections (immich, tmdb, fraimic, display, eink, scheduler).
Defaults follow the official Fraimic converter: 13.3" panel, Atkinson
dithering, brightness 1.1 / contrast 1.2 / saturation 1.2, /api/image upload
and /api/info status endpoints.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ConfigStore resolves defaults <- .env <- /data/config.json, persists only
explicitly saved values, masks secrets for clients, supports reset to
.env/defaults and drops stale or invalid saved entries on load.
HistoryStore keeps a pruned display log for anti-repeat rules. Writes use a
temp file + fsync + os.replace; corrupt files are moved aside.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Pure ASGI middleware enforces APP_API_KEY on mutating routes, /api/config
and (optionally) the image endpoints, via X-API-Key or ?api_key=. Root path
support works whether or not the proxy strips the prefix. A logging filter
redacts known secrets and api_key query parameters, including in Uvicorn
access logs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
create_app() wires CORS, auth and root path middleware, initializes the
stores in the lifespan and exposes GET /api/health, GET /api/status,
GET/PUT /api/config, GET /api/config/schema and POST /api/config/reset.
Validation errors never echo submitted values. python -m app runs Uvicorn
with proxy headers and FORWARDED_ALLOW_IPS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
validate_external_url enforces http(s), rejects embedded credentials and,
when BLOCK_PRIVATE_URLS is enabled, blocks non-public resolved addresses
unless allowlisted. read_limited/read_upload enforce the size limit while
streaming and verify_image_bytes checks real image structure with Pillow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
python:3.11-slim image running as non-root uid 1000 with a /data volume,
dependency layer caching and a /api/health HEALTHCHECK. Compose maps
./data, reads an optional .env and supports PUID/PGID and HOST_PORT.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CI runs ruff, mypy and pytest on Python 3.11/3.12 plus a Docker build and
smoke test for pushes and PRs targeting develop and main. Tags v* build
and push linux/amd64 and linux/arm64 images to GHCR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
feat: core setup (settings, persistence, auth, Docker, CI)
atomic_write_bytes (temp file + fsync + os.replace) now backs
atomic_write_json and will persist the rendered images and the upload
queue. Adds settings.queue_dir (/data/queue), pins numpy>=2.0 (NEP 50
promotion keeps the vectorized color metric identical to the official
converter) and adds a 'slow' pytest marker run as a separate CI step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Palette order, 4-bit device codes (0x0-0x6, 0x4 skipped) and the RGB+luma
distance metric from the official Fraimic converter. match_palette is a
vectorized float64 version that selects the same entry as the official
closest_palette_color, checked against a vendored copy of the official
code (tests/reference, MIT) on 20k+ colors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both kernels only diffuse error right and into the next row, so pixels on
the same x + 2y anti-diagonal are independent and are quantized as one
NumPy batch (W + 2H steps instead of W * H). Applying the down-left tap
before the right tap keeps the float32 summation order of the sequential
loop, making Atkinson bit-identical to the official converter while
running in ~0.7 s (13.3") / ~1.1 s (31.5") instead of ~40 s.
Floyd-Steinberg uses the same engine with the tuned palette metric.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
encode_bin maps palette indices to the 4-bit device codes and packs them in
the panel layout: left/right half split for the 13.3" EL133UF1 (960,000 B)
and the 8 IC blocks of bottom-to-top column-pair strips with 0x11 padding
in IC4/IC8 for the 31.5" EL315 (2,304,000 B). decode_bin is the exact
inverse and rejects invalid nibbles. Tests check byte parity with the
official packers, the spec walkthroughs and the EL315 mapping formula.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- smart_crop: official cover-scale + crop, with the window shifted to keep
  focus regions (faces) in frame; identical to the official crop fit when
  no regions are given.
- contain: official fit + centered paste on a black, white or blurred,
  darkened background; identical to the official letterbox for flat fills.
- enhance: brightness -> contrast -> saturation -> [sharpness] ->
  EDGE_ENHANCE -> SMOOTH -> SHARPEN on the picture only (official order).
- render: decode (magic bytes, EXIF orientation, alpha flattened on white),
  compose and dither in viewing orientation, rotate indices losslessly by
  landscape_rotation into the native portrait buffer, then encode the .bin.
  Produces the clean JPEG preview and an exact 6-color dithered PNG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CurrentImageStore atomically writes current.bin, current.jpg (clean
enhanced composition), current_dithered.png (exact 6-color simulation) and
current.json last as the commit marker. The stored SHA-256 detects sets
interrupted mid-write, which are then ignored instead of being served or
pushed to the frame.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
FraimicClient wraps httpx for GET /api/info (battery, charging, Wi-Fi RSSI
and IP, firmware; parsed leniently) and POST /api/image (raw .bin as
application/octet-stream, refused before sending when the size does not
match the panel). Keep-alive is disabled because the frame drops Wi-Fi in
deep sleep. Transport failures map to FraimicUnreachableError (with an mDNS
hint for .local hosts in Docker) and non-2xx answers to
FraimicResponseError. Paths and timeouts come from the fraimic config.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
DeliveryService persists the newest image as /data/queue/pending.bin +
pending.json (atomic, SHA-256 checked, restored on restart) and delivers it
through a background worker:
- continuous: immediate push; failures stay queued and retry with
  exponential backoff (30 s to 15 min); telemetry refresh every 5 min.
- deepsleep: queue only; probe GET /api/info every poll_interval_s and
  upload as soon as the frame answers; wakeup() flushes immediately.
Uploads are serialized (no double push on wakeup/worker races), an image
submitted mid-upload stays pending, a status endpoint error does not block
the upload, and a panel change discards a pending image built for the old
panel. Frame telemetry (online, last seen, battery, RSSI, firmware) is
tracked without extra network calls.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Saving the 6-color preview as an RGB PNG with optimize=True took ~1.4 s per
render. A palette PNG is pixel-identical, smaller and encodes in ~30 ms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Waking the worker (e.g. after a configuration change) no longer triggers a
telemetry request when nothing is pending; continuous mode still refreshes
telemetry every 5 minutes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- POST /api/display/upload: multipart image (MAX_UPLOAD_MB, magic-byte
  check, 413/415), optional fit override and push_to_fraimic.
- GET|HEAD /api/current.jpg, /api/current_dithered.png, /api/current.bin
  with ETag (bin hash), If-None-Match 304 and Cache-Control: no-cache;
  the dithered preview follows PUBLIC_IMAGE_ENDPOINTS like the others.
- POST /api/fraimic/push: force push current.bin (200 delivered, 202
  queued, 409 when there is no image for the configured panel).
- POST /api/fraimic/wakeup: background flush returning 202 by default,
  ?wait=true returns the delivery outcome.
- GET /api/fraimic/info: cached telemetry, ?refresh=true queries the frame
  (504 unreachable, 502 frame error, 409 no host).
- GET /api/status now reports frame telemetry, the upload queue, the last
  delivery and the current image metadata without any network access.
- BodySizeLimitMiddleware rejects oversized bodies before FastAPI spools
  multipart uploads to disk.
- Tests block external DNS so they can never reach the network.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
README gains eInk pipeline and frame delivery sections (files, endpoints,
power modes, performance) and credits the upstream converters.
.env.example warns that .local names do not resolve inside Docker bridge
networks. CLAUDE.md now matches the official frame API (POST /api/image,
GET /api/info), the Atkinson default and the /data/cache + /data/queue
layout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
np.argmin(axis=1) is typed as Any by the NumPy 2.4 stubs used on Python
3.11 in CI; wrapping it in np.asarray(..., dtype=np.intp) keeps mypy
strict happy on every supported NumPy version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
feat: eInk pipeline, Fraimic client and deepsleep delivery
Landscape mode now rotates the composition into the panel's native portrait
buffer before error diffusion, like the official --fit rotate flow, so the
.bin is byte-identical to the reference (previously ~8.6% of dither dots
differed, colour-neutral). Portrait output is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The composition area is inset by safe_margin_px on every side (default 0,
unchanged output); the margin is filled with the contain background style.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
smart_crop now keeps the largest-first subset of focus regions that fits the
crop window instead of slicing faces on opposite edges in half. FocusRegion
gains padded() so providers can leave room for hair and shoulders.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
immich.accounts holds multiple named accounts (url + api_key) plus
always_include, person_aliases, cache TTL and candidate count. Account keys
are masked in GET /api/config, restored from the stored value when a masked
or omitted key is sent back, and registered for log masking. IMMICH_URL and
IMMICH_API_KEY seed an account named 'default'; saved legacy immich.url and
immich.api_key values are migrated on load.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
iPhone HEIC originals now decode at full resolution everywhere images are
validated or rendered, including POST /api/display/upload. AVIF stays
disallowed and the magic-byte, pixel-count and truncation checks still apply.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
- BaseImageProvider/ImageAsset abstraction with typed provider errors
- ImmichClient + gateway (x-api-key header, no redirects, SSRF policy, size caps),
  contracts pinned against Immich 3.3.5
- PeopleDirectory: per-account TTL cache, aliases (IDs or names), ambiguity errors
- Face boxes -> padded FocusRegions, target people first, orientation guard
- ImmichProvider: random/album/favorites/search through one query path,
  any/all person matching, always_include merge, checksum dedupe across
  accounts, anti-repeat history, original -> fullsize -> preview downloads
- Reusable fake Immich server for tests

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
ant1fr and others added 18 commits November 15, 2026 18:45
Serve a single-page UI at / (Tailwind + Alpine from CDN, relative URLs,
light/dark, responsive) with a live dashboard, a render playground and
graphical settings, plus the endpoints it needs:

- GET /api/activity: recent renders and masked log lines (ring buffers)
- POST /api/playground/render: compare profile/dither variants, never stored
- POST /api/display/title-card: typographic card, ephemeral by default
- GET /api/tmdb/search and POST /api/tmdb/test
- POST /api/immich/test and GET /api/immich/thumbnail/{account}/{kind}/{id}

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
feat: web UI dashboard, playground and settings
- Locked Folder assets are never selected, in every pipeline
- family settings: members, private albums/people, context override
- smart_mix.discovery_share: whole-library random photo with quality gate
- POST/GET/DELETE /api/context with per-field TTL persisted in scheduler state
- advertise _smartframe._tcp.local. over mDNS (ZEROCONF_ENABLED)
- Settings: Family Mode pickers, Discovery slider; dashboard ambient card

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
feat: Family Mode, Random Discovery, ambient context and Zeroconf
…settings

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
chore: add a Portainer stack file
fix: probe the frame on first dashboard load
fix: stop buttons rendering disabled before their first use
The cover now shows the artist and album; the track title is only printed when
music.show_track_title (or the request's show_title) asks for it, and it is
always printed when there is no album. The title only counts in the content
key when printed, so every track of an album deduplicates to one picture: the
frame is not refreshed between tracks and only the expiry is extended.

BREAKING CHANGE: covers no longer print the track title by default; set
music.show_track_title to restore it. title is optional when an album is given.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
A long unbroken title (or URL, or error text) stretched the auto-sized column of
bare grids and overflowed the page. Bare grids now get a one-column minmax(0, 1fr)
track and shrinkable children (zero-specificity, so grid-cols-* utilities still
win), and the body wraps long words and clips horizontal overflow.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
feat: make the track title optional on now-playing covers
fix: stop the web UI from scrolling horizontally on phones
…and a new README

- release workflow: multi-arch image to GHCR (stable tags 1.0.0/1.0/1/latest, pre-releases only
  their exact tag), Trivy scan before the push, GitHub Release with categorized notes
- CI: multi-arch Docker dry run on pull requests to main; PR labeler from Conventional Commit titles
- CodeQL (python, javascript) and least-privilege permissions in every workflow
- docker-compose.yml pulls the published image with HOST_PORT / DATA_DIR / PUID / PGID;
  docker-compose.build.yml builds from source; .env.example documents every variable
- SECURITY, CONTRIBUTING, ROADMAP, dependabot, PR and issue templates
- README rewritten for newcomers (logo, badges, screenshots); technical docs move to the wiki

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
Stillroom is a third-party MIT project by WillCroPoint, not a Fraimic one.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
chore: release pipeline, production compose, community files and new README
@github-actions github-actions Bot added the chore Maintenance, CI, refactoring label Nov 18, 2026
@github-advanced-security

Copy link
Copy Markdown

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

  • The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
  • Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
  • You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

Comment thread app/clients/http_images.py Dismissed
Comment thread app/core/sessions.py Fixed
ant1fr and others added 2 commits November 18, 2026 22:27
The password is mixed into the HMAC message instead of a SHA-256 fingerprint, which
removes a CodeQL weak-hashing alert. Existing sessions are invalidated once.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
fix: derive the session signing key without a bare password hash
Comment thread app/core/sessions.py Fixed
ant1fr and others added 4 commits November 18, 2026 22:41
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
fix: derive the session signing key with a cached PBKDF2
- GET /api/health is now a public handshake: api_version, min_api_version, auth, capabilities
- Zeroconf TXT carries api_version and min_api_version
- version is read from the package metadata (pyproject), bumped to 1.0.0rc1
- docs/API_CONTRACT.md with the compatibility policy and a generated endpoint index
- docs/openapi.json exported by scripts/export_openapi.py, guarded by a drift test
- CLAUDE.md rule: API changes must update the contract and regenerate the schema

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VzFCH4ztqBYejkvLvFgnaq
feat: add the API compatibility contract and capability discovery
@ant1fr
ant1fr merged commit 689cfa0 into main Nov 19, 2026
12 checks passed
@ant1fr
ant1fr deleted the develop branch November 19, 2026 10:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

chore Maintenance, CI, refactoring

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants