Proposal: community-built iOS companion app and minimal stable API

[charmmmz]

Hi! Following up on the conversation with Kayden, I have been sketching a community-built iOS companion app for Tesserae.

The original motivation is deliberately practical: make Tesserae easier to use day to day without requiring users to understand server URLs, device tokens, renderers, or the full admin UI. The app would complement Tesserae rather than reproduce its web interface, and would be clearly labelled as a community-built client rather than an official app.

What the native app would add

The first useful release would focus on the places where native iOS APIs add real value:

1. Discover a Tesserae instance on the local network, with manual URL and QR fallbacks.
2. Pair once and reconnect using a revocable per-client credential.
3. List displays and saved dashboards.
4. Send a saved dashboard to its bound displays or an explicitly selected display.
5. Send one photo from the app or the iOS Share Sheet, with Fit/Fill and target selection.
6. Expose a small set of App Intents for Shortcuts.
7. Open the existing Tesserae web UI for editing and advanced management.

Dashboard editing, widget/plugin administration, schedules, firmware controls, and general server administration would remain in the web UI.

History/resend, rich previews, and detailed telemetry are useful follow-ups, but I do not think they need to block the first stable integration.

Current server surface reviewed

I reviewed current main at 5ff2b1f / Tesserae 0.203.3.

Tesserae already has most of the underlying business logic:

• /healthz;
• the versioned device API for panel firmware;
• POST /api/v1/push with a global webhook token;
• DeviceRegistry, PageStore, PushManager, and EventLog;
• the existing Send-page image pipeline and History republish support;
• optional generic _http._tcp mDNS advertisement;
• internal page/device JSON and the experimental privileged MCP API.

For a shipped iOS app, I would prefer not to depend directly on firmware device tokens, the global webhook credential, MCP, Flask session cookies, or internal web routes. Those surfaces represent different trust boundaries or are not stable external contracts.

The proposal is therefore a small stable adapter over the existing stores and PushManager, not a second rendering or delivery implementation.

Proposed minimum Companion contract

The exact namespace is open for discussion; /api/app/v1 is used below only as a working name.

Discovery and pairing

• GET /api/app/v1
  • Unauthenticated capability probe.
  • Product/server/API versions, supported features, pairing availability, and server-advertised upload limits.
  • No display names, dashboard names, secrets, or other household content.
• POST /api/app/v1/pair
  • Exchange a short-lived, single-use Companion-purpose code for a per-client bearer token.
  • The QR contains only the base URL and temporary code, never the long-lived token.
• DELETE /api/app/v1/session
  • Revoke the presented client token.

The admin UI would list paired clients by name and last use and allow each one to be revoked independently. A fixed Companion role is enough for the first release, although storing explicit scopes would keep future narrowing possible.

The existing six-digit, single-use, ten-minute firmware pairing mechanics look reusable, but Companion and firmware codes should be separate credential purposes so one kind of code cannot mint the other kind of token.

Read models

• GET /api/app/v1/devices
  • Stable target ID and display name.
  • Panel width, height, gamut, and orientation.
  • Optional battery, RSSI, firmware, and last_seen_at where available.
• GET /api/app/v1/dashboards
  • Stable ID, name, grid/canvas kind, and bound device IDs.
  • A web-management URL may be included.

I would avoid promising a generic online / sleeping / offline state. Many e-ink devices intentionally sleep for long periods, so raw last_seen_at plus an optional server-derived fresh / stale / unknown value seems more honest. Dashboard list previews can also be added later or fetched on demand rather than forcing renders while listing.

Writes

• POST /api/app/v1/dashboards/{dashboard_id}/push
  • Omitted device_ids uses the dashboard bindings.
  • Explicit device_ids overrides the targets.
  • The server remains responsible for validating devices and rendering for their panel dimensions.
• POST /api/app/v1/images
  • Multipart still-image upload.
  • Explicit target IDs.
  • Existing server vocabulary: fit or fill.
  • Actual byte/pixel/codec limits advertised by the capability endpoint.
• GET /api/app/v1/jobs/{job_id}
  • Only if writes use asynchronous acceptance.

Both write routes should accept an Idempotency-Key, particularly for Share Extension and Shortcuts retries, so an uncertain network response cannot cause an accidental second e-ink refresh.

Questions for maintainer review

1. Namespace: Would you prefer a separately versioned /api/app/v1, or a resource under the existing stable namespace such as /api/v1/companion?
2. Asynchronous jobs: A render/publish can take roughly 5–15 seconds, and Share Extensions have a limited lifetime. Would a small persisted job record with accepted, running, and terminal states be acceptable, or would you prefer the first dashboard endpoint to return a synchronous PushResult?
3. Quiet hours: My suggested default is to respect quiet hours, while allowing an explicit user-initiated Send/Share action to request an override. Shortcuts would respect quiet hours by default and expose the override as an explicit option. Does that match the intended server policy?
4. Credential storage: Is a dedicated Companion token registry acceptable, or should this extend an existing credential store with a distinct credential type?
5. Discovery: Would a dedicated _tesserae._tcp.local service be acceptable alongside the existing _http._tcp advertisement? Manual URL and QR pairing would remain mandatory fallbacks.
6. Image policy: Which image codecs and initial resource limits would you be comfortable treating as a stable server contract?

If this direction looks reasonable, my next step would be to turn the accepted subset into a compact OpenAPI proposal with example requests/responses and contract tests. The iOS client can then be built against fixtures while the server endpoints are implemented in small pieces.

[dmellok]

This direction works for me. Framing it as a thin adapter over the existing stores and PushManager, clearly labelled community-built, is exactly what I'd want, and keeping editing and admin in the web UI while staying off the firmware tokens, webhook credential, MCP, and session cookies is the right call. Answers to your six, in order:

1. Namespace. Go with a separately versioned /api/app/v1. It's a different trust boundary and audience from the firmware device API, and I want it to version on its own rather than being pinned to /api/v1's lifecycle. /api/v1/device/* stays untouched.

2. Async jobs. Yes, async. A push or image render is 5 to 15 seconds and a Share Extension won't survive that, so return 202 accepted plus a persisted job record and poll GET /jobs/{id}. Keep the states minimal: accepted, running, and a terminal succeeded/failed with a reason. Combined with the Idempotency-Key, a resubmit after an uncertain response resolves to the same job instead of a second render.

3. Quiet hours. Your policy matches the server's. Automation respects quiet hours; an explicit user Send/Share is intent and may request an override. Default the app and Shortcuts to respecting them and expose the override as a deliberate option. This mirrors /api/v1/push today (respect by default, 202 with quiet when everything is asleep), so reuse that response shape so the app can tell "sent" from "held for quiet hours".

4. Credentials. Dedicated Companion registry, separate from device tokens and the webhook token. Per-client bearer tokens with a name and last-use, independently revocable in the admin UI, as you describe. Keep the Companion pairing code a distinct purpose from the firmware code so neither can mint the other's token. Ship a single Companion role now, but persist a scope field so we can narrow later without a breaking change.

5. Discovery. Yes to a dedicated _tesserae._tcp service alongside the existing _http._tcp, so the app finds Tesserae specifically instead of scanning every HTTP service. Manual URL and QR stay mandatory fallbacks. zeroconf is already a dependency, so the cost is small.

6. Image policy. Accept JPEG, PNG, HEIC/HEIF, and WebP; Pillow plus pillow-heif already cover these server-side. The renderer fits to panel dimensions anyway, so generous input is fine and the real constraint is decode cost. Advertise a byte cap and a decoded-pixel cap from the capability endpoint rather than baking numbers into the client. A sane starting point is roughly 25 MB and an 8K max edge, but treat the advertised values as the contract so we can tune without an app release.

A few of your other calls I want to agree with explicitly so they don't get lost:

• The freshness model (raw last_seen_at plus an optional server-derived fresh/stale/unknown, no fake online/offline) is the honest one for e-ink. Devices sleep for long stretches by design, so an online/offline dot would just be wrong.
• Deferring dashboard previews to on-demand rather than rendering while listing is right; listing should never force renders.
• Idempotency-Key on both write routes is a hard requirement for Share and Shortcuts.
• The unauthenticated capability probe leaking no household content (no display or dashboard names, no secrets) is the correct boundary.

If this subset looks right, turn it into the compact OpenAPI proposal with example requests/responses and contract tests. I'll implement the server side in small pieces against that, and you can build the client against fixtures in parallel.

[charmmmz]

Thanks — I’ve turned the accepted subset into a standalone, public iOS companion repository:

https://github.com/charmmmz/tesserae-companion-ios

The compact proposal and shared fixtures are here:

• OpenAPI 0.2.0
• JSON fixtures
• Contract notes

I made one explicit clarification while encoding the examples: Job lifecycle remains accepted / running / succeeded / failed, while the successful business outcome is nested as result.status: published | quiet. That keeps “quiet hours correctly respected” separate from infrastructure failure. Both write operations require Idempotency-Key, and the fixtures cover accepted, published, quiet, failed, and idempotency-conflict shapes.

The Swift models decode the same fixtures, and local checks currently pass:

• OpenAPI/fixture contract tests: 4/4
• TesseraeKit tests: 7/7
• unsigned iOS Simulator build
• simulator UI journey

The repository is Apache-2.0, clearly labelled community-built, and keeps live HTTP, Bonjour, QR, and Keychain work behind explicit boundaries until the server contract lands. History, resend, and previews remain follow-ups.

The two details I left intentionally server-advertised rather than fixed are job retention and idempotency retention; the fixtures currently use 24 hours as a proposal default. Happy to adjust those and any naming/details before you start the first server slice.

[dmellok]

This is a great turnaround, thanks. The repo is in better shape than most community clients ever get to, and having the fixtures decode in both the contract tests and the Swift models before a single server endpoint exists is exactly the right order to do this in.

Agreed on the result.status: published | quiet nesting. Keeping the job lifecycle about infrastructure and the business outcome separate underneath it is cleaner than what I had in my head, and it means "held for quiet hours" can never be mistaken for a failure. Take that as accepted.

On the two you left open, 24 hours for both works for me and I'm happy for them to stay server-advertised rather than fixed in the contract. Job retention barely matters since the client polls within seconds and only needs the record to survive an app switch or a dropped connection. Idempotency retention at 24 hours matches what most payment APIs settle on, so it won't surprise anyone.

I'll start the server side in small pieces against OpenAPI 0.2.0. Rough order: capability probe, then pairing and the Companion token registry, then the read models, then the async job record and the two write routes, then _tesserae._tcp. I'll tag a minimum compatible Tesserae version once the write routes land so the client has something concrete to gate on.

One housekeeping thing while we're setting boundaries, and none of it is a reaction to anything you've done. Your repo already says App Store use of the Tesserae name is subject to my approval, so let's write down what that approval actually is rather than leaving it open.

You have my permission to use the Tesserae name and mark for Tesserae Companion on the App Store and in the repo, on these terms:

• Always described as community-built, never official, in the listing and in-app
• No third party advertising SDKs
• No analytics or telemetry leaving the device without explicit opt-in
• No selling or sharing user data
• No paywalling functionality the web UI gives away free

Separate from those terms, and not a condition of anything: my preference is a free app, since Tesserae itself is free and self-hosted and I'd like the companion to feel like part of that. But a paid app, a one-off unlock, a tip jar, or sponsorship are all fine and I'd rather you had the option than not. You're doing real work here and I'm not going to ask you to do it in a way that can never recover the cost. Whichever way you go, just give me a heads up first. Treat the preference as a preference, not a condition, and don't let it override what makes the app sustainable for you.

If the terms above are ever broken the name permission lapses and the app gets renamed, but I don't expect to ever think about that again. Drop these into ATTRIBUTION.md or a BRAND.md in your repo, whichever you prefer, and that's the whole arrangement documented.

Also worth pinning down before TestFlight: the handover path if you stop maintaining it. Your README mentions notice and a practical handover, which I appreciate. A line about what happens to the App Store listing specifically would make it real.

[charmmmz]

Thanks — this is very clear and generous, and I am aligned with all of those terms.

I will update ATTRIBUTION.md to record the name and mark permission, the community-built positioning, the advertising, analytics, telemetry, and user-data restrictions, and the boundary around functionality that the web UI provides for free. I will link back to this discussion so the source and terms of the permission remain easy to verify.

I will also make the App Store handover path concrete. If I stop maintaining the app, I will provide advance public notice and first seek to transfer the repository and App Store listing to a mutually acceptable successor. If no responsible successor is available, I will stop distribution rather than leave an unmaintained listing in place, while keeping the final source and release available where practical.

I will give you a heads-up before making any monetization decision. For now the focus is on getting the native integration and real-device experience right.

The 24-hour job and idempotency retention defaults are accepted on the client side. I will keep building against OpenAPI 0.2.0 and gate real-server support on the minimum Tesserae version you tag. In parallel I will continue with Bonjour discovery, QR pairing, connection persistence, the Share Extension, and App Intents while the server endpoints land.

Thanks again — this gives the project a very clear technical and product boundary.

[dmellok]

Server side is moving. Phase 1 is on edge now (v0.206.0): the capability probe, pairing with the Companion token registry, and the two read models, the first three items in the order above.

Details worth having as you point the app at a real server:

• GET /api/app/v1 is unauthenticated and leaks no household content, just versions, features, pairing availability, and limits. features currently advertises ["devices","dashboards"] only; it grows to include dashboard_push, image_push, and jobs as those routes land, so gate on the list rather than assuming the full set.
• limits already carries the 24h job_retention_seconds and idempotency_retention_seconds plus the ~25 MB / 8K-edge image caps, even though the write routes aren't live yet, so the client can read them from day one.
• Pairing is a distinct credential purpose from firmware pairing: a firmware code can't mint a companion token and vice versa. Codes are the existing 6-digit / 10-minute single-use mechanic; the token comes back once as tc_live_... and is hashed at rest. Operators issue codes and revoke paired apps from Settings → Devices.
• instance.timezone returns the configured IANA zone, or UTC when the server is set to system-local (I don't resolve the host zone to an IANA name). Fine for display; flagging in case you do date math against it.

Next slice is the async job record and the two write routes, then _tesserae._tcp. I'll tag the minimum compatible version when the write routes land, as planned. The vendored 0.2.0 contract + fixtures run in the server suite too, so if the client repo's copy drifts I'll see it.

[dmellok]

Phase 2 is on edge now (v0.207.0), so the whole 0.2.0 contract has a server behind it. The write path, job polling, and _tesserae._tcp are all live.

Write routes:

• POST /api/app/v1/dashboards/{id}/push and POST /api/app/v1/images both return 202 with the persisted job, a Location header pointing at the job, and Retry-After. Poll GET /api/app/v1/jobs/{id}; it carries Retry-After while non-terminal.
• Idempotency-Key is required on both (16-128 chars). Same key + same payload replays the original job; same key + changed payload is 409 idempotency_conflict. So a Share/Shortcut resubmit after a dropped response resolves to the one job, never a second render.
• Lifecycle (accepted/running/succeeded/failed) stays about infrastructure; the business outcome is nested result.status: published | quiet on a succeeded job, with reason: all_targets_in_quiet_hours on a quiet hold. Quiet is never a failure.

Quiet hours and targeting:

• Respect by default; pass override_quiet_hours: true for an explicit user Send. On a mixed push, the job resolves published and result.device_ids lists only the displays actually sent to; a fully-quiet push resolves quiet. There's no partial "some sent, some held" status, which matches the schema.
• Image push is multipart (image part + request JSON part). It validates media type (415 unsupported_image) and both the encoded byte cap and the decoded max edge (413 image_too_large) against the advertised limits. HEIC/HEIF/WebP decode server-side.

Discovery and gating:

• features now advertises all five (devices, dashboards, dashboard_push, image_push, jobs); keep gating on the list.
• When mDNS is enabled (Settings → App, opt-in), the server advertises _tesserae._tcp beside _http._tcp, TXT record path=/api/app/v1, api=companion, v=1. Manual URL and QR stay the mandatory fallbacks.
• Job and idempotency retention are 24h, already in limits.

I'll tag v0.207.0 as the minimum compatible Tesserae version so you have a concrete gate to build against. Shout if any of the write-path or quiet-hours behaviour above needs adjusting before you wire up the Share Extension and Shortcuts.

[dmellok]

Quick correction on the version gate: 0.207.0 is on edge, not a stable release tag yet. Build against edge >= 0.207.0 for now; the capability probe's server_version and features list are the reliable runtime signals, so gate on those rather than assuming a surface is present. I'll cut the stable v0.207.0 release once it's had some edge soak, and that tag is the one to hard-gate on.

[charmmmz]

Real-device update: I paired the current iOS build with a v0.207.0 edge server and successfully sent a photo end to end to a Seeed reTerminal E1004. Pairing, Companion auth, device discovery/listing, multipart upload, job polling, and the physical refresh all worked.

While tightening the Displays and Dashboards UI I found the next small API gap: read-only previews. The server already has the underlying implementation (PushManager.latest_render_for plus /preview/{device}.png, and the cached /compose/{page}/preview.png), but I do not want the app to depend on LAN/session-gated internal routes.

Would you be open to an optional additive previews feature, not required for Companion V1 compatibility, with:

• GET /api/app/v1/devices/{device_id}/preview
  • Companion bearer auth with devices:read
  • latest viewable composition PNG; 200 image/png, 304 with ETag, and 404 when no frame exists
  • stable latest-full-composition semantics, acknowledging that patch overlays may be newer
• GET /api/app/v1/dashboards/{dashboard_id}/preview
  • Companion bearer auth with dashboards:read
  • on demand only, never rendered while listing
  • 200 image/png when cached; 202 plus Retry-After while a background render is prepared; 404 when unknown
  • optional device_id query for target dimensions; when omitted, use the existing resolved preview target or virtual panel

The capability probe would advertise previews only when both are available. The app would lazy-load visible cards, send bearer auth, cache by ETag, and keep its placeholder when the feature is unsupported. No token would appear in URLs, and existing list responses would not need to change.

For dashboard data freshness, I am happy to initially define this as a faithful cached visual preview, invalidated by layout, configuration, or target-dimension changes, rather than promising live widget data. A refresh TTL or an explicit fresh-render option could remain a later addition.

[dmellok]

Good to hear the full chain worked on real hardware, pairing through physical refresh on an E1004.

Yes to previews as an optional additive feature, advertised only when both endpoints are available, off the LAN/session-gated internal routes, no token in URLs, and no change to the existing list responses. The shapes you proposed are right; a few specifics so we implement to the same contract:

Device preview (GET /api/app/v1/devices/{device_id}/preview, devices:read):

• 200 image/png of the latest full composition, 304 on If-None-Match, 404 when no frame exists yet.
• ETag is the composition digest (the renders are already content-addressed), so revalidation is cheap and stable across restarts.
• Latest-full-composition semantics, acknowledged that a patch/overlay may be newer than the composition it patched. The preview is the composition, not the on-glass patched frame.

Dashboard preview (GET /api/app/v1/dashboards/{dashboard_id}/preview, dashboards:read):

• 200 image/png when a cached composition exists, 202 + Retry-After while a background render is prepared, 404 when unknown. Never rendered while listing.
• The 202 render runs through the same async worker the write jobs use, so a prepare is bounded and idempotent rather than a synchronous stall on the request.
• Optional device_id query for target dimensions; when omitted, the existing resolved preview target, then the virtual panel.
• Your cached-visual-preview definition is the right V1 scope: a faithful preview invalidated by layout, config, or target-dimension changes, not a promise of live widget data. A refresh TTL or an explicit fresh-render option can come later without a breaking change.

The capability probe will list previews only when both are live, so the app can keep its placeholder when the feature is absent. It's additive and non-breaking, so it rides edge like the rest; I have a release gated on unrelated in-flight work, so it'll land on edge first and be in the stable cut when that goes out.

[dmellok]

previews is implemented and on edge (v0.208.0), matching what we agreed:

• GET /api/app/v1/devices/{device_id}/preview (devices:read) serves the latest full composition PNG, 200 image/png, ETag = the composition digest, 304 on If-None-Match, 404 when the display is unknown or nothing has rendered yet. It's the composition, not the on-glass patched frame, so a live tap overlay can be newer than what's served.
• GET /api/app/v1/dashboards/{dashboard_id}/preview (dashboards:read) returns 200 image/png from cache, 202 + Retry-After while a background render is prepared, 404 when unknown. Never rendered while listing. Optional device_id query for target dimensions; omitted, it uses the dashboard's resolved preview target, then the virtual panel. ETag is the content+dims token, so an unchanged dashboard revalidates to 304. It's a faithful cached visual preview invalidated by layout / config / target-dimension changes, not a promise of live widget data (TTL / explicit fresh-render can come later).

Both reuse the existing render machinery but sit behind Companion bearer auth, off the LAN/session-gated internal routes, no token in any URL. Existing list responses are unchanged.

Capability advertisement: features includes previews only when the server has a renderer available to prepare dashboard previews (device previews serve existing renders regardless, but the pair is advertised together so the app enables the whole surface at once). If it's absent, keep your placeholder.

One contract housekeeping note: I kept my vendored copy of app-v1.openapi.yaml frozen at 0.2.0, so previews isn't in its features enum or paths yet. Whenever you fold the two preview endpoints + the previews feature into the published contract (0.2.x), I'll refresh my vendored copy to match and add it to the schema-validated set. Until then the server advertises it additively.

[charmmmz]

A couple of follow-ups have surfaced now that the Companion is running against a real server and physical E1004. They are related from the app UX point of view: the display preview needs to be trustworthy, and Activity should eventually become the canonical place to understand and repeat sends rather than remaining a local 24-hour Job cache.

Neither proposal changes the original product boundary. Editing, schedules, plugins, firmware, deletion/administration, and general server management would stay in the web UI.

1. Device preview: show the device-transformed result

Motivation

Fit and Fill both publish correctly to the physical display, but the Displays card currently looks like Fit in both cases. The app is not re-applying a fixed fit mode there; it displays the PNG returned by:

GET /api/app/v1/devices/{device_id}/preview

Looking through the current path, the endpoint deliberately selects composition_digest. That PNG is saved before the per-renderer transform, while image Fit/Fill, panel sizing, flip/orientation, underscan, and renderer-specific palette/quantisation happen later. The current response therefore cannot show the result that was actually prepared for the device.

This is not a problem for Dashboard compositions that already match the panel dimensions, but it is visible for arbitrary photo sends, which is the main place where users need the preview to be reliable.

Proposed semantic

For the Companion device preview, I would prefer:

• the latest device-specific, viewable preview after Fit/Fill and panel geometry have been applied;
• exact panel dimensions/aspect and orientation;
• ideally the same underscan and colour/quantisation stage used for the device;
• ETag based on that device-preview artifact;
• still no promise that a newer live patch/overlay is included.

For PNG renderers, the final renderer artifact may already be directly viewable. Packed binary renderers would need a parallel PNG generated from the same transformed image before packing. One possible implementation is a preview_digest alongside digest and composition_digest in the latest-render record, with a composition fallback only for legacy entries.

Because previews is new and additive, my preference would be to tighten the existing device-preview semantic before it becomes a long-lived contract. If you would rather preserve the current composition semantic, an additive query/endpoint for the rendered stage also works, but the app only needs the device-specific result for its Displays card.

Would you be comfortable making that semantic change, and where in the renderer pipeline would you consider the most honest reusable PNG preview point?

2. Server-backed History and Resend inside Activity

Motivation

The current Activity tab is backed by Companion Jobs cached by the app. That is useful for accepted / running / terminal feedback, but it only knows about work initiated by that app and Job retention is intentionally 24 hours. It cannot show sends from the web UI, Home Assistant, schedules, buttons, webhooks, or another family members phone.

Tesserae already owns the canonical pieces: EventLog, the History view model, stored composition digests, delivery-target snapshots, and PushManager.republish(event_id). The app should consume a scoped adapter over those rather than create a second history store.

I would not add a separate History tab. Activity would become one timeline:

• non-terminal local Companion Jobs at the top for immediate progress;
• server History rows below for completed and historical sends;
• refresh the History list when a Job reaches a terminal state;
• thumbnails, source, target displays, timestamp, outcome, and error on each row;
• Resend as an action on a resendable row.

Proposed minimum additive surface

Advertise a history feature only when this complete subset is available.

GET /api/app/v1/history

• Companion bearer auth; using the existing read scopes is sufficient for V1 if you prefer not to migrate stored tokens for a new scope.
• Push events only, newest first.
• Cursor pagination such as before_id plus a server-bounded limit.
• Optional source, device_id, and include_skipped filters can be additive; only cursor + limit need to block the first client.
• Suggested item fields:
  • opaque id;
  • created_at;
  • source and a friendly label;
  • original device_ids snapshot;
  • status, duration_seconds, and optional error;
  • preview_available;
  • server-computed resendable.

GET /api/app/v1/history/{history_id}/preview

• Authenticated image/png, ETag/304, and 404 when the artifact has been evicted.
• A composition thumbnail is sufficient here: this is identifying historical content, unlike the Displays card where the final device treatment matters.

POST /api/app/v1/history/{history_id}/resend

• push:write, required Idempotency-Key, and the same 202 Job response/polling semantics as the existing writes.
• V1 resends only to the original target snapshot. Sending an already-sized composition to a different panel/aspect can be misleading, and the original image may no longer exist.
• Respect quiet hours by default; an explicit user action may request override_quiet_hours: true, matching the existing contract.
• Return not-resendable/not-found cleanly when the digest or composition artifact is gone.
• Record a new History row with source=resend, preserving the original rather than mutating it.

If it is cheap to expose correlation, history_event_ids on the terminal Job result or job_id on History items would make reconciliation exact. It is not required for the first UI: the app can show only non-terminal local Jobs above the canonical History list, which avoids duplicate completed rows without heuristic matching.

Deliberately out of scope for this slice

• deleting or clearing server history from the app;
• editing schedules/rotations/decks;
• changing resend targets across panel dimensions;
• retaining original uploaded photos indefinitely;
• promising History as a permanent archive beyond the servers existing cap/retention policy.

If these directions look reasonable, I can turn the accepted subset into the next Companion OpenAPI revision and fixtures before either side implements it. The preview correction seems like the smaller immediate fix; History/Resend can remain an additive follow-up after the first stable Companion integration.

[charmmmz]

One more small Companion contract follow-up surfaced while comparing photo sends with the current Tesserae Send page: image fit modes.

The server-side Send pipeline currently supports five modes:

• fit: preserve aspect ratio and show the whole image with background around it;
• fill: preserve aspect ratio and crop the overflow;
• blur: show the whole image over a blurred cover-cropped backdrop;
• stretch: resize directly to the panel dimensions, potentially distorting the image;
• center: keep the source pixel size, centre it, clip overflow, and leave background where it is smaller than the panel.

The current Companion 0.2.0 contract and /api/app/v1/images intentionally expose only fit and fill. I do not think the app should present all five as equal primary choices, but it would be useful for the Companion contract to express the full server capability rather than permanently fixing the mobile surface to two modes.

Proposed product treatment

The main Send and Share UI would prioritise:

1. Fit
2. Fill
3. Blur Background

Blur seems especially useful for phone photos whose aspect ratio does not match a portrait or landscape display: it avoids both large empty areas and aggressive subject cropping.

stretch and center would be placed under an Advanced or More menu and shown only when advertised by the server. Stretch is deliberately destructive, while Center is a pixel-sensitive operation whose result depends on the uploaded source dimensions rather than only its aspect ratio, so neither should have the same prominence as the photographic modes.

Proposed additive contract change

Would you be open to:

• advertising a supported_image_fit_modes list from the capability endpoint, with the exact field location/name open for discussion;
• validating POST /api/app/v1/images against the server-advertised list rather than a Companion-specific hard-coded Fit/Fill subset;
• allowing a History item to include the selected fit mode when known, as useful descriptive metadata for Activity and resend;
• keeping the final device-specific preview from the previous proposal as the visual source of truth, particularly for Blur and Center, instead of requiring the app to duplicate the renderer exactly.

The client would remain backward-compatible: when the field is absent it would assume ["fit", "fill"], matching 0.2.0. It would never send a mode the connected server has not advertised.

My preference is therefore full capability at the protocol level, a focused three-mode photographic UI, and two opt-in advanced modes. If that direction works, I can include the advertised modes, request enum expansion, History metadata, examples, and fixtures in the same next Companion OpenAPI revision as the accepted follow-ups.

[charmmmz]

A small semantic clarification to tie the preview, History, and fit-mode proposals together:

History preview should consistently mean the stored composition artifact, not a device-final rendering. The visible difference depends on how that composition was produced:

• A saved Dashboard is composed at the target panel dimensions before fan-out, so its History composition is already close to WYSIWYG, apart from later renderer-specific orientation, underscan, calibration, palette, and quantisation work.
• A photo/file/URL send enters fan-out as the input image. Its History composition therefore identifies the photo that was sent, but it is not the result after Fit, Fill, Blur, Stretch, or Center and device-specific processing.

That distinction is intentional and useful: the History/Activity thumbnail answers what content was sent, while the Displays preview answers what was prepared for this particular device. History does not need to retain a second final artifact for every renderer merely to identify the row.

For photo Resend to be faithful, however, the History record needs to preserve the selected fit mode and the resend path needs to reuse it. Otherwise replaying the same composition can produce a different crop or treatment from the original send. This is the reason for including fit-mode metadata in the proposed History item, rather than an expectation that the History thumbnail itself show the post-fit result.

[dmellok]

Good calls, and yes to the additive shape. Answers per item:

• supported_image_fit_modes in the capability probe: yes. I'd put it under limits as image_fit_modes, alongside image_content_types, so it sits with the other image constraints the client already reads. Absent means ["fit", "fill"], per 0.2.0.
• Validate /images against the advertised list rather than a hard-coded subset: yes. The server supports fit / fill / blur / stretch / center, so it will advertise all five and validate the posted mode against that list. Backward-compatible, since the client never sends a mode the server hasn't advertised.
• Three-mode photographic UI (Fit / Fill / Blur), Stretch/Center under Advanced: agreed, that's the right treatment. blur is genuinely the best default for a phone photo onto a mismatched panel. The server treats all five equally at the protocol level; prominence is the client's call.
• History fit-mode metadata: yes, cheap and useful for Activity + resend. I'll include the selected mode on the History item when known.
• Device-final preview as the visual source of truth for blur/center: yes, and it dovetails with the previews endpoints already on edge, so the app never has to duplicate the renderer.

Fold image_fit_modes + the /images enum expansion + History metadata + fixtures into your next OpenAPI revision alongside previews, and I'll implement the server side against it.

[charmmmz]

Thanks — I have now folded the accepted directions into a draft Companion contract 0.4.0. The API namespace remains /api/app/v1; 0.4.0 is the contract-document revision, not a breaking API-version change.

Final additive shape

Image modes

• Optional limits.image_fit_modes advertises the exact accepted values.
• When absent, clients assume ["fit", "fill"] for 0.2 compatibility.
• The expanded enum is fit / fill / blur / stretch / center.
• /images validates against the advertised list.
• The iOS client presents Fit, Fill, and Blur as the primary choices, with Stretch and Center under More.

History capability

The probe advertises history only when the complete subset is available:

• GET /api/app/v1/history?before_id=...&limit=...
  • newest first, opaque cursor pagination;
  • rows carry id, created_at, source, label, original device_ids, status, optional duration_seconds and error, preview_available, resendable, and optional fit.
• GET /api/app/v1/history/{history_id}/preview
  • authenticated composition PNG with ETag/304 and 404 when unavailable.
• POST /api/app/v1/history/{history_id}/resend
  • required Idempotency-Key, optional override_quiet_hours defaulting to false, and the existing async Job semantics;
  • V1 resends to the original target snapshot and reuses the retained fit mode;
  • creates a new History row rather than mutating the original.

A History preview deliberately remains the source composition: for a Dashboard it is already close to WYSIWYG, while for a photo it identifies the original image rather than the post-fit device result.

Device preview and reconciliation

• The device preview semantic is tightened to the latest device-specific viewable PNG after image layout and panel geometry. Renderer palette/quantisation should be represented when that stage can expose a reusable PNG. It still does not promise that a newer on-glass patch or overlay is included.
• A terminal Job may include optional result.history_event_ids. This gives Activity exact Job-to-History reconciliation; clients can otherwise refresh History after completion.

All of this remains capability-gated. A base 0.2 server is still compatible, gets Fit/Fill only, and shows local Job Activity without server History.

Client and contract status

The OpenAPI revision, JSON fixtures, stateful fixture-server behavior, Swift models/transport, all five preview geometries, and the unified Activity UI are drafted in the Companion working tree. Contract tests and the fixture-backed History/preview/resend vertical slice pass. I will publish these as a Companion Draft PR next so the full schema and examples are reviewable rather than pasting the complete YAML here.

For server implementation, the contract divides cleanly into:

1. advertise and validate image_fit_modes, plus tighten the device-preview artifact;
2. add the read-only History list and composition-preview routes;
3. add resend and optional history_event_ids correlation.

If this final naming and split still look right, the Draft PR can be treated as the implementation contract. I am also happy to help with a Tesserae server Draft PR if that is more useful than keeping the two sides separate.

[charmmmz]

The Companion 0.4 contract and client implementation are now published as a Draft PR: charmmmz/tesserae-companion-ios#1.

The first commit is the contract-only review surface: OpenAPI, fixtures, compatibility notes, and the stateful fixture-server behavior. The second commit contains the capability-gated Swift models/transport and UI implementation. This should make it possible to review the server contract independently from the client presentation.

I have kept the PR Draft while the Tesserae server surface is pending. Once you have had a chance to confirm the schema, we can use the three implementation slices listed there for server work and then run the real-server/device validation.

[dmellok]

Contract 0.4 accepted

Accepting 0.4 as the implementation contract, History included. The additions map onto existing server machinery, so the three slices are largely adapter work over the push EventLog, the retained composition PNGs, and the existing republish path.

Image fit modes

• limits.image_fit_modes advertises fit / fill / blur / stretch / center.
• POST /images validates the posted mode against the advertised list.
• Absent remains ["fit", "fill"] for 0.2 compatibility.

History and resend

• The list is the canonical push EventLog, newest first, cursor-paginated on before_id.
• Each row's thumbnail is the composition PNG already retained for that push.
• Resend reuses the existing republish path: the original target snapshot and the retained fit mode, producing a new row and never mutating the original.
• kind: history_resend and the optional result.history_event_ids correlation are both accepted.
• One retention behaviour to record, and the preview_available / resendable flags already express it: composition artifacts are pruned from the render store over time, so older rows will report both as false once their PNG ages out. The list stays complete; only the thumbnail and resend fall off the tail.

Previews

• History preview is exactly the stored composition PNG, as specified. Direct match.
• Device preview needs one clarification recorded:
  • For a Dashboard, the composition PNG is device-final, since it is composed at panel dimensions.
  • For a photo, the composition PNG is the source image. Fit/Fill/Blur and panel rotation are applied inside the renderer transform and are not currently persisted as a viewable PNG.
  • The V1 device preview will therefore return the composition PNG: device-final for dashboards, source-identifying for photos. This is consistent with the contract wording, "palette and quantisation should be represented when a reusable PNG can be produced from that stage."
  • If photo device-previews after fit and geometry are required for the Blur/Center presentation, I will add a post-fit preview-PNG emit to the .bin renderers as a fast-follow. The fitted, rotated frame already exists mid-transform and only needs to be persisted. My preference is to ship the composition-PNG device preview first and layer that on, rather than block V1.

Server implementation

• Yes to a Tesserae server Draft PR against the three slices; additional hands on the server are welcome.
• I will review before merge, since this is authentication and contract surface, but the blast radius is small: the EventLog, republish, the render directory, and the companion auth already exist.
• Treat the 0.4 contract as the implementation target.

[charmmmz]

The first server batch is now available as Draft PR #153: five image fit modes, canonical History list/composition preview, idempotent resend to the original targets with quiet-hours handling, and exact history_event_ids where available. The device-final post-fit preview remains the planned follow-up batch.

[charmmmz]

Should a Companion device preview represent the server's latest frame or the device's last-served frame?

After using the device-specific previews from #154 with a deep-sleep REST display, I noticed a semantic distinction that may be worth discussing before we build more UI around the preview.

The current device preview follows latest_render_for(device). This accurately represents the latest logical full frame Tesserae has rendered for that device.

However, a sleeping e-ink device may still be showing an older frame:

1. Tesserae renders a new frame while the device is asleep.
2. The server's latest-render pointer changes immediately.
3. The Companion Display card begins showing the new preview.
4. The physical display continues showing the previous frame until its next wake and /frame request.

This means the current preview answers:

What has Tesserae most recently rendered for this device?

rather than:

What frame did this device most recently wake and fetch?

The main product question is whether the second meaning is useful enough to model explicitly. My intuition is that a Display card is more naturally understood as device state, so showing the last frame served to the device may be less surprising than showing a pending server frame.

A minimal server-only approach could be:

• assign a per-device delivery revision whenever a new delivery intent is created;
• when an authenticated device requests /frame and receives a 200 or 304, persist:
  • last_served_revision;
  • last_served_digest;
  • its associated preview_digest;
  • last_served_at;
• derive fetch_pending by comparing the latest and last-served revisions;
• let the Companion display preview use the last-served preview while optionally indicating that a newer frame is waiting for the next wake.

A revision is needed in addition to the digest because Resend or forced refetch may intentionally deliver identical bytes again.

This would not be a strict physical-display acknowledgment. A successful /frame response does not prove that the artifact download and panel refresh completed. I would therefore describe the state as last_served or delivery_state, rather than displayed or confirmed.

No firmware change would be required for the initial version. A future firmware acknowledgment could make the state stricter if that ever proves worthwhile.

Questions:

1. Do we want the Companion Display card to represent the server's latest frame or the device's last-served frame?
2. Is last-served state useful enough to justify a small persisted per-device delivery record?
3. Should the existing preview endpoint change meaning, or should a separate last-served preview endpoint be added?
4. Is it acceptable for this state to be available initially only for REST polling devices, with other transports reporting it as unknown?
5. Should the server-latest preview remain available separately for administration or diagnostics?

If we decide that the server-latest meaning is preferable, the Companion can instead label it explicitly and avoid presenting it as the screen's current image.

[dmellok]

Good distinction, and worth handling. Answers in order:

1. The Displays card should represent device state where the server can know it. A frame the server just rendered but a sleeping panel hasn't fetched isn't "what's on the wall," so server-latest becomes a pending signal rather than the card's source of truth.
2. Yes, track last-served: record the digest handed out on each REST /frame 200 fetch. One string per device, no new store.
3. Extend rather than add an endpoint. GET /devices/{id}/preview keeps returning the served frame, and the devices list gains a small boolean (e.g. has_pending_render, true when server-latest differs from last-served) so the app can badge "update pending." A second preview endpoint isn't worth the surface.
4. REST-first is fine. MQTT and push devices don't poll /frame, so they have no reliable served signal and fall back to server-latest.
5. Keep server-latest retrievable; it's what the preview returns today. The pending badge is just the two digests differing.

[charmmmz]

That makes sense, and I’m happy with the simpler digest-only model. For the Display card, a forced refetch of identical bytes does not change the visual result, so a separate delivery revision does not seem necessary.

One clarification before implementation: I read points 3 and 5 as meaning that the Companion endpoint GET /api/app/v1/devices/{id}/preview would switch to the REST device’s last-served frame, while server-latest would remain available through the existing internal/admin preview path. Is that the intended split?

One implementation detail from #154: the device artifact digest and the logical preview_digest are separate. Once server-latest advances, serving the older last-served visual will therefore require carrying forward its associated preview_digest (or equivalent render snapshot) and keeping that preview protected from garbage collection. I assume those fields can live alongside the existing persisted latest-render record, so this still needs no separate store.

With that interpretation, has_pending_render can simply compare the current wire digest with the last-served wire digest; a REST /frame 200 advances the last-served snapshot, while MQTT/push devices continue to fall back to server-latest.

If that matches your intent, I’m happy to sketch the server change next.

[dmellok]

Confirmed, that's the split. I checked it against the current code; a few notes:

• GC (your Widget process isolation + split secrets out of /data (phase 3) #3) needs more than the existing grace window. PushManager._live_digests() today protects the latest render, a ~60 s "previous render" grace, and warmed deck frames. A last-served preview that's been superseded by a newer render falls out of all three within ~60 s and is pruned, so the last-served snapshot needs to contribute its preview_digest to _live_digests() directly, not lean on the previous-render grace.

• Advance last-served on /frame 200 and 304. In rest_api.get_frame the served digest (latest["digest"], and latest["preview_digest"] alongside it) is available on both branches. A 304 is the device confirming it already holds the latest frame, so recording last-served there is what clears has_pending_render once a sleeping panel catches up. Recording only on 200 would leave the badge stuck.

• has_pending_render (your Docker image + docker-compose for one-command install #4): a digest comparison (latest vs last-served) is the right signal for the badge; it answers "does the screen differ from the latest render." The delivery revision you raised earlier only matters if you also want a forced resend of identical bytes to read as pending, and for a visual "update waiting" badge that isn't needed, since identical bytes mean the device already shows the current content. I'd keep the badge digest-based.

On server-latest for diagnostics (your #2/#5): /preview/<id> and /mirror/<id> already serve a device's latest render (the composition PNG), so the "what did the server render last" view stays covered without a second Companion endpoint. Go ahead with the server sketch against that.

[charmmmz]

Companion photo framing: reusing #45 for multi-target sends

A small follow-up surfaced while looking at the in-app Send Photo flow. The Companion can already preview the advertised Fit, Fill, Blur, Stretch, and Center modes, but Fill is necessarily a fixed centred crop today. On iOS, the natural next interaction would be to drag the photo to choose the subject and pinch to zoom before sending.

Before proposing a new contract, I found the earlier Discussion #44 and the resulting Issue #45. The normalized source crop and server-side processing direction there makes sense, and I would prefer to reuse it rather than introduce a separate client-baked crop path in the Companion.

The extra case the Companion introduces is multi-target fan-out. One POST /api/app/v1/images request can target displays with different aspect ratios. A single normalized crop rectangle snapped to one panel can be exact for that panel but may need another crop or letterboxing on a second target.

Would it make sense to treat the server-side crop step described in #45 as the shared primitive, while allowing the Companion to send normalized framing intent such as:

• focus_x and focus_y in the source-image coordinate space;
• zoom relative to the minimum Fill scale;
• rotation as a future-compatible optional addition rather than a first-slice requirement?

The server could resolve that intent into a concrete normalized crop rectangle for each target panel, clamp it so no empty edge is exposed, then feed the result through the existing per-target renderer fan-out. Omitting framing would preserve the current centred Fill behavior.

Proposed roadmap

Phase 1: smallest complete vertical slice

• Optional, capability-gated framing on POST /api/app/v1/images.
• Uploaded photos only, and only when using Fill/custom framing.
• One shared focus and zoom across the selected targets, resolved independently for each panel geometry.
• The in-app Send preview supports drag, pinch, reset, and switching among selected target previews.
• History and Resend retain enough framing metadata to reproduce the original send.
• No Picture Gallery/Web editor work, Share Extension editor, per-target overrides, or dither controls in this slice.

Phase 2: richer multi-display editing and reuse

• Per-target or per-aspect-ratio framing overrides, with an Apply to all action.
• The same editor in the Share Extension.
• Reopen a History photo, adjust its framing, and send it again.
• Optional local subject or face detection on iOS only to choose an initial focus; manual framing remains authoritative.
• Reuse the shared server crop primitive from Picture gallery: on-web crop/zoom + dithered preview #45 in the eventual Web Send/Picture Gallery surfaces.

Questions before turning this into a contract

1. Does reusing the normalized crop operation from Picture gallery: on-web crop/zoom + dithered preview #45 as the server primitive fit the direction you had in mind?
2. For the Companion API, would you prefer an exact normalized crop rectangle, or focus plus zoom that the server resolves per target? If one exact rectangle is preferred, what should mixed-aspect target semantics be?
3. For faithful History and Resend, should the server retain the original framing intent, the resolved per-target crop rectangles, or rely on retained final compositions?
4. Should this be advertised as a separate image_framing capability, or as an optional image limit/feature under the existing image_push surface?
5. If the direction is acceptable, would the same workflow as the previous Companion additions work: a contract-only Draft PR with fixtures and client models first, followed by the server adapter after review?

This is intended as a focused photo-send enhancement, not an attempt to move general image editing or the full Picture Gallery into the Companion. The main goal is to make the high-frequency mobile send flow precise while sharing the underlying server work with #45.

[dmellok]

This is a good direction, and one server crop primitive shared across the Companion send and the web gallery is exactly right. Answers to your five, plus sequencing:

1. Reuse #45's crop, and the shared primitive now exists rather than being a plan. SourceCrop (a normalized {x,y,w,h} + clockwise rotate) and apply_source_crop, applied inside fit_to_panel before the fit, are in (#175). So the Companion's focus+zoom intent resolves into a SourceCrop rect per target panel and feeds the exact same call the Send/gallery path uses. #45's web editor and your Companion framing become two callers of the one primitive; the exact rect is the degenerate single-target case.

2. Focus + zoom, resolved per target. An exact rect is aspect-locked, so a second target forces a re-crop or letterbox. focus_x/focus_y in source-normalized [0,1] + zoom relative to the min Fill scale is aspect- and resolution-agnostic: the server resolves it per panel and clamps so no empty edge shows (the clamp is server-owned; client intent is advisory). Rotation as an optional future field is fine.

3. Retain the intent for reproduction; keep leaning on retained compositions for exact resend. Resend to the original targets is already pixel-exact by republishing the retained composition. Reproduce / re-target / adjust needs the original intent (focus + zoom + fit) plus the source reference. Don't persist the resolved per-target rects as source of truth, they're derived and useless once the target set changes.

4. A separate additive image_framing feature flag, advertised only when the server can resolve intent, consistent with how previews / webpage_push are gated. Older servers ignore the fields and fall back to centred Fill; put the numeric bounds under limits. Uploaded photos + Fill/custom only, as you scoped.

5. Yes, same workflow. Contract-only Draft PR with fixtures + client models first, I review, then I take the server adapter. Keep the first contract to your Phase 1 slice.

On sequencing: the crop primitive is in now, so build your framing intent to resolve into SourceCrop and we share the math end to end.

[charmmmz]

Update after #175: proposed Companion 0.6 framing contract

I reviewed PR #175 after it merged. It supplies the important server-side primitive we were discussing: normalized SourceCrop coordinates, optional rotation, crop application, and a crop input to fit_to_panel. That looks like the right foundation for Companion framing.

As I read it, #175 intentionally stops below the Companion boundary: it does not advertise an API capability, accept framing on POST /api/app/v1/images, resolve one crop per target, or persist framing for History/Resend. I have therefore drafted the next layer as a proposed additive Companion contract 0.6 rather than treating #175 as an end-to-end implementation.

Proposed additive shape

• advertise a separate image_framing feature;
• when advertised, also publish limits.image_framing_max_zoom, so clients do not hard-code an editor range;
• allow uploaded-image requests using fit: fill to include:

"framing": {
  "focus_x": 0.62,
  "focus_y": 0.38,
  "zoom": 1.35
}

• keep focus_x and focus_y in normalized, orientation-correct source-image space;
• define zoom: 1 as ordinary Fill and larger values as tighter crops;
• resolve the same intent independently for each target panel, then convert it to the SourceCrop accepted by Picture: source crop primitive + Panel-view dithered preview (#45) #175;
• omit framing for the existing centered Fill behavior;
• defer rotation from the first slice, even though the underlying primitive can carry it.

For each target, the proposed deterministic resolution is:

1. derive the ordinary Fill crop dimensions from the source and target aspect ratios;
2. divide both crop dimensions by zoom;
3. center the crop on focus_x / focus_y;
4. clamp the origin so the crop remains inside normalized source bounds.

This lets one send target portrait and landscape displays without baking a single panel-specific crop into the request.

History and resend

The proposed History item may return the original normalized framing intent. A resend reuses that intent for the original target snapshot. Internally, the server can retain the original intent, resolved crops, or both, as long as a faithful resend remains possible after the source composition is retained.

Compatibility and implementation order

This remains independently capability-gated and is not part of the five-feature Companion compatibility floor. Existing servers remain compatible, and existing app, Share Extension, and Shortcut sends continue to omit framing.

I have prepared the OpenAPI schema, separate forward-looking capability fixture, valid and invalid multipart fixture behavior, Swift models/transport, mixed-target crop-resolution tests, and compatibility/roadmap notes locally. Contract tests, a real local URLSession multipart vertical slice, TesseraeKit tests, and the full iOS Simulator build pass.

The implementation order would now be:

1. agree on this contract shape;
2. add the thin Tesserae Companion adapter that validates framing, resolves SourceCrop per target, and preserves History/Resend behavior;
3. enable drag, pinch, reset, and target-preview switching in the in-app Send editor only when image_framing is advertised;
4. consider Share Extension editing, per-target overrides, and rotation later.

Does this naming and focus-plus-zoom resolution fit the intended use of #175? In particular, are you comfortable making image_framing_max_zoom mandatory whenever image_framing is advertised, and returning the original intent on History while leaving resolved crop storage as a server implementation detail?

If so, I can publish the contract/client work as the same kind of reviewable Draft PR used for the earlier Companion additions before we touch the server adapter.

[dmellok]

0.6 shape looks right, and it lands where #175 was aimed. Confirmations, then one thing that needed fixing on my side first.

1. Naming and resolution fit #175. Focus + zoom resolving to a SourceCrop per target is what the primitive was shaped for, and your four-step resolution runs in the order fit_to_panel expects (crop, then fit). Deferring rotation is fine, the field stays available.

2. image_framing_max_zoom mandatory whenever image_framing is advertised: yes. A capability that doesn't publish its own bounds just relocates the hardcoding into the client. I'll advertise 4. Treat it as the editor bound rather than a quality promise: the server still clamps the resolved rect to source bounds, and a heavy crop of a small photo will be soft on a large panel regardless of what the editor allowed.

3. History returns the original intent, resolved rects stay internal: yes. Resend to the original targets remains pixel-exact by republishing the retained composition; the intent is what makes reproduce and re-target work. Resolved rects are derived and go stale the moment the target set changes, so they're a cache at best.

4. EXIF orientation, which was a real gap on my side. There was no exif_transpose anywhere in the server: every Image.open worked on the stored pixel buffer. Cameras commonly store a landscape buffer plus an orientation tag instead of rotating pixels, so a portrait phone photo was already reaching panels sideways, and framing would have made it worse: if the app measures focus_x/focus_y against the visually-correct image while the server crops the raw buffer, the crop silently lands in the wrong region, and only for photos carrying a non-default orientation tag.

Fixed in v0.225.0: fit_to_panel now normalizes orientation ahead of apply_source_crop, so normalized coordinates address the image as displayed on both sides of the wire. Regression tests cover a rotate-90 tagged photo through both the plain fit and the crop path. Rendered compositions carry no EXIF, so it's a no-op for dashboards.

Please state in the contract that focus_x/focus_y are in orientation-normalized source space, and include a rotated-EXIF fixture so the crop-resolution tests exercise it rather than assuming it.

5. Same workflow, yes. Contract-only Draft PR with fixtures and client models, I review, then I take the server adapter: validate framing, resolve SourceCrop per target, thread the intent through History and Resend.

[charmmmz]

Thanks — I have now published the contract/client slice as a Draft PR:

charmmmz/tesserae-companion-ios#5

It applies the decisions from your review:

• image_framing_max_zoom is mandatory with image_framing, with the initial advertised value set to 4;
• focus_x / focus_y are explicitly defined in EXIF-orientation-normalized source space;
• History exposes the original framing intent for reproduction and re-targeting, while resolved per-target crop rectangles remain server-internal;
• the test suite now includes a real JPEG carrying EXIF orientation 6 and verifies the crop against the visually upright dimensions from both the Python contract tests and the Swift upload-preparation path.

The PR is intentionally limited to the accepted Companion 0.6 contract, fixtures, client models, and tests. It does not add the native drag/pinch editor or a Tesserae adapter yet.

Could you please review the OpenAPI wording and the rotated-EXIF fixture in the Draft PR? If those match your intended server semantics, the contract boundary should be ready for your adapter implementation, and I can keep the iOS editor gated on the eventual image_framing capability.

[dmellok]

Reviewed, details in charmmmz/tesserae-companion-ios#5 (comment). Short version: the OpenAPI wording and the rotated-EXIF fixture match the server semantics, with two non-blocking asks (a clamp-engaging fixture case, and deriving the fixture server's zoom validation from its advertised limit). The contract boundary is ready and I'll take the server adapter next.