Proposal: native Lineups authoring in Tesserae Companion

[charmmmz]

Following our Discord conversation, where you said:

“I’d love to be able to build schedules/decks/rotations in the app.”

I have been looking at how that idea maps onto Tesserae’s newer unified Lineups model and the existing Companion trust boundary.

The original Companion proposal in Discussion #147 deliberately kept schedules, rotations, decks, and general editing in the web UI. Since then, Tesserae has consolidated those concepts behind the Lineups surface and unified deck storage through #167. The earlier read-only schedules proposal in #172 also predates that unification.

I would therefore like to revisit the boundary, but as a focused native Lineups workflow rather than reproducing the complete web administration UI.

Proposed native experience

The first authoring flow would mirror the four user-facing intents in Tesserae’s current setup wizard:

1. Show one dashboard at a set time

   • one dashboard;
   • daily trigger at a server-local time.

2. Keep one dashboard fresh

   • one dashboard;
   • re-render and publish on a repeating interval.

3. Cycle through several dashboards

   • one display;
   • an ordered set of dashboards;
   • a dwell time for each dashboard.

4. Flip between dashboards by hand

   • one display;
   • an ordered set of dashboards navigated by button, tap, or swipe.

The app would present those four simple choices rather than asking users to understand the historical Schedule / Rotation / Deck distinctions.

Tesserae would remain authoritative for storage, validation, dashboard binding, scheduling, rendering, conditions, quiet hours, and delivery.

Smallest complete first slice

My proposed first slice would include:

• list Lineups, grouped by display;
• show enabled state, member dashboards, current dashboard, and next action/time when known;
• create all four basic Lineup intents;
• edit an existing Lineup only when the app can represent it completely;
• enable or disable a Lineup;
• push/activate a Lineup;
• step backwards or forwards through a manual Lineup;
• play a selected dashboard from a Lineup;
• deep-link to the Tesserae web editor for advanced configurations.

The app would not silently simplify an existing Lineup. A Lineup using conditions, fallback pages, priority mode, smart sync, advanced time windows, or another unsupported field would remain readable and controllable, but editing would open the web UI.

This is especially important because a partial client update must never reset server-owned fields it did not understand.

Proposed Companion API direction

I suggest exposing the user-facing resource as:

/api/app/v1/lineups

rather than exposing DeckStore or recreating separate schedule, rotation, and deck resources in the Companion API.

A possible resource surface is:

GET    /api/app/v1/lineups
GET    /api/app/v1/lineups/{lineup_id}
POST   /api/app/v1/lineups
PATCH  /api/app/v1/lineups/{lineup_id}
POST   /api/app/v1/lineups/{lineup_id}/actions

Deletion could remain in the web UI for the first slice.

For creation, the request could use a simple authoring intent:

daily | interval | cycle | manual

The server could translate that intent into the unified model.

For reads, I do not think the four authoring intents are sufficient to describe every existing record. The response may need to retain the underlying concepts, for example:

advance: manual | timer | both
trigger: cycle | interval | daily

along with a server-derived indication such as:

native_editable: true | false
requires_web_reason: ...

The exact field names are open; the important behavior is that the server, not the app, decides whether a record can be safely edited through the basic native surface.

Capabilities and scopes

I suggest independently advertised capabilities, tentatively:

lineups
lineup_authoring
lineup_control

and explicit token scopes such as:

lineups:read
lineups:write

One permission question is important: existing Companion tokens currently carry an explicit persisted scope list. I do not think a new ability to modify household schedules should be silently granted to every previously paired client.

Would you prefer:

• re-pairing or explicit operator approval before granting lineups:write;
• a migration of the existing fixed Companion role;
• or a separate control/manage role in the Companion settings page?

Dashboard and display binding

The current web wizard is display-aware and can bind an unassigned dashboard to the selected display during creation.

I think that behavior should remain server-owned rather than requiring the app to make several internal configuration calls.

A possible rule would be:

• a dashboard already compatible with the selected display is accepted;
• an unassigned dashboard may be bound by the server when the request explicitly permits it;
• a dashboard bound only to another display returns a stable conflict response rather than being silently moved.

For example, creation might include an explicit intent such as:

{
  "bind_unassigned_dashboards": true
}

Does that match the binding behavior you would want from a native client?

Concurrency and partial updates

For updates, I propose returning an ETag or equivalent resource version and requiring If-Match on PATCH.

If a Lineup has changed in the web UI since the app loaded it, the server should reject the stale update and let the app refresh. The app should never overwrite a newer server configuration.

A partial update must also preserve every omitted field. Reordering dashboards, renaming a Lineup, or changing its interval must not reset conditions, trigger details, smart-sync settings, or future fields unknown to the client.

Creation versus activation

I suggest keeping these separate:

• creating or editing saves the Lineup definition;
• pushing/activating it is an explicit action.

An immediate push, step, or play action can reuse the existing Companion Jobs, Idempotency-Key, History correlation, and explicit quiet-hours override pattern. Merely saving a definition should not unexpectedly refresh a physical display.

Initially out of scope

To keep the first contract reviewable:

• deleting Lineups;
• authoring conditions;
• fallback-dashboard editing;
• priority and conflict-policy editing;
• smart-sync tuning;
• advanced active windows;
• Canvas/dashboard editing;
• exposing internal Deck, Schedule, or Rotation compatibility projections;
• trying to reproduce the complete web Lineups editor.

Those can remain available through the returned web-management URL.

Questions

1. Does the Discord idea of building schedules/decks/rotations in the app map to the current unified Lineups surface as described here?
2. Is /api/app/v1/lineups the right public resource name, with Deck remaining an internal model?
3. Do the four basic authoring intents match the smallest useful native slice?
4. Should existing advanced Lineups remain read/control-only until the native client can represent them completely?
5. How would you like new lineups:read / lineups:write permissions granted to existing and future paired clients?
6. Should binding unassigned dashboards remain an explicit server-side creation option?
7. Is ETag / If-Match acceptable for protecting web and app edits from overwriting each other?
8. Should enable/disable and play/step/push controls land with authoring, or as a separate follow-up capability?

If this direction fits, I can prepare the same kind of contract-only Draft PR used for the previous Companion additions:

• additive OpenAPI paths and schemas;
• capability and scope fixtures;
• valid, advanced/read-only, conflict, and stale-update examples;
• Swift models and transport interfaces;
• contract tests;
• no server adapter or native UI implementation yet.

After the contract boundary is reviewed, the Tesserae adapter and capability-gated iOS surface can be implemented as separate slices.

[dmellok]

Before the contract, one thing about the current state that changes the sequencing rather than the design.

Lineups is a unified surface over a model that is only partly unified. Deck carries the superset of fields and a legacy_kind marker, and the list view merges everything, but creation still fans out to three stores: the wizard's cycle button posts to the rotation store, daily and interval to the schedule store, and manual to the deck store. So the piece your proposal leans on, "the server translates that intent into the unified model", is the piece that does not exist yet. POST /api/app/v1/lineups today would have to become a fourth caller fanning out to the same three stores, which is the coupling the proposal is trying to avoid.

That is my problem to fix, not yours, and it argues for splitting your first slice in two: read plus control needs none of it and can land now; authoring lands on top of a single write path once I have one.

Answers in your order:

1. Yes. The four intents you list are the wizard's own four, so the mapping is exact.
2. Yes. lineups public, Deck internal. That split already exists in the UI, where Lineups is the surface name and deck is the store noun. No reason to leak the internal one.
3. Yes, with the note that your manual is the wizard's deck mode.
4. Yes, and server-computed. Deck has around a dozen advanced fields (conditions, fallback page, priority and conflict mode, smart sync and its lead time, day-of-week and wrap-around windows, minimum hold), and any of them can be set from the web UI. The app should never infer editability itself. native_editable plus a reason field is the right shape.
5. Something has to be built either way. Pairing issues a fixed scope set with no upgrade path, so a token paired today simply lacks a new scope and gets a 401. My preference: lineups:read joins the default set for new pairings, and lineups:write is an explicit per-token toggle in the Companion settings page, off by default, no re-pair required. Household scheduling is not something an existing pairing should silently acquire, and forcing a re-pair to grant it punishes the wrong people.
6. Yes, server-owned, and an explicit request flag rather than a default. Worth knowing that the web behaviour is not uniform: creating a cycle binds an unassigned dashboard to the display, and the deck editor's save does the same, but daily and interval do not, because schedules carry a page and no display at all. So the flag is meaningful for cycle and manual only, and the contract should say so rather than implying it applies to all four.
7. Yes. Nothing uses If-Match today, ETag is only a conditional-GET validator on previews, but the write path already has Idempotency-Key and Jobs, so this fits the existing shape. Agreed on preserving omitted fields; with the field count in point 4 that is the failure mode I would most expect from a partial update.
8. Controls first, as above.

The contract-only PR is welcome. Two things I would like settled in it: the read shape has to carry enough of the underlying model that an advanced record is still fully describable when native_editable is false, and the action endpoint should distinguish saving a definition from touching a display, which your creation-versus-activation split already gets right.

[dmellok]

Read + control is live as of v0.287.0, so the first half of your slice has real endpoints to target rather than a proposal:

GET  /api/app/v1/lineups
GET  /api/app/v1/lineups/{id}
POST /api/app/v1/lineups/{id}/actions   enable | disable | next | previous | play

Details that affect your client:

• Each Lineup carries native_editable plus requires_web_reason, decided server-side exactly as you proposed. Anything using conditions, a fallback dashboard, priority mode, smart sync, day or time-of-day windows, or a home card is false, with a reason naming the field.
• current is a list of {device_id, page_id} rather than a single page, and the step actions move each display from its own position. A Lineup on two panels doesn't drag them to a shared index.
• Enable and disable return the updated Lineup immediately. next, previous and play return a job with Location and Retry-After, same as a dashboard push, and need an Idempotency-Key.
• Repaint jobs report kind: dashboard_push. Inventing a kind would have meant widening the closed enum in your contract from this side, which is yours to decide; if the app wants to tell them apart, name it in the contract PR and I'll follow.
• Pairing now grants lineups:read and lineups:control. A token paired before v0.287.0 lacks both and gets a 401 on these routes until it re-pairs, which Companion: per-token scope grants, and a path for adding new scopes #207 will fix properly with per-token grants.

Authoring is unchanged from what I said earlier: it waits on #204, the single write path. Creation still fans out to three stores, so POST /lineups has nowhere to land yet.

Two things I'd still like settled in your contract PR: whether the read shape above carries enough to describe an advanced Lineup completely when it isn't natively editable, and the job-kind question. The paths aren't in the vendored spec on my side, deliberately, so there's nothing of mine for you to work around.

[charmmmz]

Thanks — I have aligned the Companion 0.8 read/control contract and Swift client with the live v0.289.2 behavior. I have settled the two remaining contract questions as follows.

1. Read shape

Keep the implemented projection unchanged:

• top level: id, name, enabled, intent, device_ids, dashboards, current, next_advance_epoch, advance, trigger, interval_minutes, fires_at, anchor, native_editable, requires_web_reason, web_url
• each dashboards[] item: page_id, name, effective dwell_minutes, and missing

Add the fields needed to describe an advanced Lineup completely:

• top level: entry_page_id, home_page_id, home_timeout_minutes, refresh_interval_minutes, end_at, days_of_week, priority, smart_sync, smart_sync_lead_seconds, mode, min_hold_minutes, window_start, window_end, fallback_page_id
• each dashboards[] item: raw refresh_interval_minutes, links, and conditions

The internal legacy_kind marker stays private. The Swift reader treats the additive fields as unknown when they are absent, so it can already read the deployed v0.289.2 response without mistaking missing advanced data for safe authoring defaults.

2. Job kind

Please use kind: lineup_action for the asynchronous next, previous, and play jobs. The canonical History source remains companion; the distinct Job kind is only so Activity can identify explicit Lineup control instead of presenting it as an ordinary Dashboard push.

The action contract otherwise follows the live implementation:

• enable / disable: 200 LineupResponse, no Idempotency-Key
• next / previous / play: 202 Job, Idempotency-Key and override_quiet_hours required
• paint actions may include a bound device_ids subset; play also requires a Lineup page_id

Pairing uses lineups:read plus lineups:control. For tokens created before those scopes existed, the Companion will ask the user to pair again rather than adding a migration path. lineups:write remains a separate future authoring permission and is outside this slice.

I have kept this contract/client-only: no native authoring endpoints or Lineups UI are included yet.

[dmellok]

Both settled as you asked, live on edge in v0.291.0.

Read shape. The projection carries the full set now: entry_page_id, home_page_id, home_timeout_minutes, refresh_interval_minutes, end_at, days_of_week, priority, smart_sync, smart_sync_lead_seconds, mode, min_hold_minutes, window_start, window_end, fallback_page_id, and per dashboard the raw refresh_interval_minutes, links and conditions. Nothing that was already there moved or changed shape.

Two details worth knowing:

• The per-dashboard refresh_interval_minutes is the raw override, so it's null when the dashboard inherits the Lineup's cadence. dwell_minutes next to it stays the effective value. That's deliberate, so "inherits" is distinguishable from "set to the same number" without you having to compare against the parent.
• conditions are serialised as stored: source_kind, source_id, operator, value, with value's shape depending on the pair. links carry target_page_id plus exactly one of button or zone.

legacy_kind stays private, as agreed.

Job kind. next, previous and play return kind: lineup_action. History source is unchanged at companion. That meant widening the kind enum in the vendored spec copy on this side, marked as errata pending your re-vendor, same as the two features and two scopes from the read/control slice.

Your absent-means-unknown reader is the right call and it's what makes the rest safe. Nothing in the action contract, the scope pairing, or the response codes moved from what you tested against in v0.289.2.

On re-pairing for pre-existing tokens: agreed, no migration path from here either. The per-token grant work in #207 is scoped to lineups:write when authoring lands, which is still behind #204's write path being wired to POST /lineups.

[charmmmz]

Thanks — I checked the v0.291.0 projection against the Companion and the full read shape plus lineup_action already match the 0.8 client.

I found one small web_url issue while testing “Open in Tesserae”: lineup_dict() currently returns /decks/{id}, but the editor GET route is /decks/{id}/edit; /decks/{id} does not appear to be a route. Could the projection use url_for("decks.editor", deck_id=deck.id) (and add a response assertion) so the advertised link lands on the editor?

I’ll add a narrowly scoped Companion fallback for already-deployed v0.287–v0.291 responses that only upgrades an exact /decks/{id} path to /edit; correctly formed and other URLs remain untouched.

[dmellok]

Good catch, and it's worse than a wrong path: /decks/{id} was never a route at all. The only GET a deck id has is the editor, so that link 404'd for every Lineup from v0.287.0 through v0.291.0.

Fixed in v0.291.1. web_url is resolved with url_for("decks.editor", deck_id=deck.id) and passed into the projection rather than built there, since that module has no app context and typing the path out is exactly how this happened. The test asserts three things: the literal value, that it equals what url_for produces (so renaming the route fails the test instead of shipping another dead link), and that fetching it returns 200. That last one is what I should have had in the first place; the original test only checked the field was present.

Your narrow fallback for v0.287–v0.291 is the right call, please keep it. Those releases are out and I'd rather your users get a working button than a correct complaint.

Nothing else moved: the read shape and lineup_action are as you verified them.

[dmellok]

Authoring is in, v0.292.0. One change needs your attention before 0.8 ships, so I've put it first.

A missing permission now answers 403, not 401

I'd parked this earlier as needing coordination. It stopped being optional once lineups:write existed: 401 tells a client its credential is dead and to pair again, but the remedy for a missing optional permission is an operator toggle in Settings, so a client following 401 re-pairs and lands in exactly the same place with the same failure.

• Valid credential, missing scope: 403, error.code: "forbidden"
• Missing, invalid or revoked credential: 401, unchanged

If your client branches on 401 to trigger re-pairing, that branch will now fire only when it should. This applies to every scope, not just the Lineup ones.

Authoring

POST  /api/app/v1/lineups            201 + ETag, needs lineups:write
PATCH /api/app/v1/lineups/{id}       200 + ETag, needs lineups:write + If-Match

Create takes the four intents and goes through the same builder the web wizard uses, so a Lineup authored from the app and one authored from the web are the same record made the same way. Body: intent, name, page_ids, optional device_ids, dwell_minutes, interval_minutes, fires_at, anchor, plus bind_unassigned_dashboards (opt-in; a dashboard already on another display is never moved). A page_ids entry that doesn't exist is a 404 rather than a Lineup with a step that can never render.

Three refusals, all deliberate:

• Web-only records refuse the edit with 400 and a message naming the reason, so a client that can't see conditions can't flatten them.
• A field outside the authoring set is rejected, not ignored (400 naming the field). Dropping it silently would let the app believe it wrote something it didn't.
• A stale If-Match is 412 precondition_failed. Every response that hands out a Lineup carries its ETag, including create. A missing If-Match on PATCH is a 400.

Fields a PATCH doesn't mention keep their stored values, and a reordered dashboard keeps its links, conditions and refresh override.

Errata on this side

Three additions to the vendored spec copy, all marked pending your re-vendor: error codes forbidden and precondition_failed, and the lineup_authoring capability (now advertised in the handshake alongside lineups and lineup_control).

lineups:write is still not granted at pairing. It's a per-client toggle in Settings, Companion, which takes effect on the next request with no re-pair.

[charmmmz]

One read/control edge case surfaced while testing Daily Lineups against the current contract.

Daily and interval Lineups created through the schedule path intentionally project device_ids as an empty array. The engine still fires them schedule-style to the dashboard own bound displays, and Companion can place such a Lineup under the correct Display using that dashboard binding.

However, POST /api/app/v1/lineups/{id}/actions currently defaults targets from deck.device_ids and also filters an explicit device_ids subset against deck.device_ids. With the empty array above, play always returns invalid_target: “The lineup has no bound displays.” In Companion this leaves the Daily play control with no valid target; merely enabling the button client-side would only expose the server error.

Which server-owned representation would you prefer here?

1. Expose a computed control target set such as resolved_device_ids or effective_device_ids separately from the explicitly authored device_ids; or
2. Let the action endpoint fall back to the member dashboard bindings when deck.device_ids is empty, matching the existing schedule-style engine behavior.

The second option seems closest to the current Daily/Interval semantics, but I do not want Companion to infer action applicability or target authorization itself. Once target resolution is server-owned, Companion can use the returned effective targets consistently while preserving device_ids as the explicit Lineup binding.

I will also add a fixture covering a Daily Lineup with device_ids: [] once we settle the intended behavior.

[charmmmz]

Thanks — we are starting the native create/edit implementation against the v0.292.0 authoring contract. I have two narrow follow-ups; neither needs to block the client work.

1. Read the current permission grant

lineups:write can be granted or withdrawn after pairing and takes effect on the next request, but the Companion only receives scopes in the original pairing response. Its persisted PairedSession.scopes therefore becomes stale, and there is currently no authenticated read endpoint with which the app can distinguish “authoring available but not granted” from “granted” before the user fills and submits the editor.

Would you be comfortable adding an authenticated session read, for example:

GET /api/app/v1/session

with a small response such as:

{
  "token_id": "...",
  "scopes": ["devices:read", "lineups:read", "lineups:control", "lineups:write"]
}

The app will treat this as progressive enhancement: while the endpoint is absent it can keep authoring visible behind the lineup_authoring capability and handle a save-time 403; once present it can show the permission state and guidance before editing. A URL for the relevant Companion settings surface would also be useful if there is a stable route you want clients to open, but it is not essential.

2. Unknown Dashboard IDs on PATCH

POST /api/app/v1/lineups checks every page_ids entry against PageStore and returns 404 for an unknown Dashboard. On PATCH, apply_patch() currently rebuilds a new DeckPage for an ID not already in the Lineup without applying the same existence check.

The native picker will only submit Dashboards it has read, so we can proceed safely for the normal path. There is still a delete-between-read-and-save race. Is the PATCH difference intentional, or should an unknown newly-added page_id receive the same 404 as creation?

On the iOS side we will keep Lineup type fixed during edit, send only changed patchable fields, require the ETag from a fresh individual GET, surface 412 precondition_failed without overwriting, and continue sending advanced/non-native-editable records to the web editor.

[dmellok]

Three answers, live on edge in v0.295.0.

Daily and interval targets

Option 2, with a piece of option 1 next to it. The action endpoint resolves targets the way the engine does: deck.device_ids when the Lineup carries one, otherwise the union of its member dashboards' own bindings. The same resolver produces resolved_device_ids on the projection, so what the app targets and what the server paints can't drift.

• device_ids is unchanged: still the explicit authored binding, empty for schedule-path records.
• resolved_device_ids is what an action will touch. Identical to device_ids whenever one is set.
• An explicit device_ids subset on an action is filtered against the resolved set rather than the authored one, so a Daily Lineup accepts a subset now. A display outside it is still invalid_target.
• current is computed over the resolved set too, so a Daily Lineup reports the dashboard its display is on instead of nothing.
• A Lineup that reaches no display at all, however it's bound, still answers invalid_target.

Worth knowing for your fixture: a Daily Lineup authored through POST /lineups with device_ids does keep them, so device_ids: [] is specifically the shape web/schedule-created records have. Both are covered here.

Permission read

GET /api/app/v1/session, valid credential only, no scope required:

{"token_id": "ct_...", "scopes": ["devices:read", "..."], "settings_url": "/settings/companion"}

Scopes are read off the token record, so a grant or withdrawal shows up on the next call. settings_url is the Companion settings page, relative and resolved with url_for rather than typed out, the same treatment web_url got. Advertised as the session_read capability; the name is provisional, so rename it in your contract PR if you'd rather.

Unknown dashboard on PATCH

Not intentional. It now answers 404 for a page_id that doesn't exist, same as create. Only newly added ids are checked: a member dashboard deleted after the Lineup was built already reports missing: true, and refusing the edit would leave you unable to remove it.

Errata

One addition to the vendored spec copy, session_read in the capability features enum, pending your re-vendor. resolved_device_ids needs none, since the Lineup paths aren't described there.