Partial persistent sessions through bindable space templates

[eghere]

Concept
Scroll Spaces is single-handedly my most favorite feature about Scroll. Today, however, a Space refers to live containers/views. Those are necessarily transient: after a compositor restart, crash, shutdown, or application exit, the original views no longer exist. This is expected on Wayland, where there is no general-purpose protocol for a compositor to recreate arbitrary application windows and restore them to a prior layout. I am interested in discussing the groundwork for a partial, user-implemented solution in Scroll.

I am not proposing general Wayland session restoration. Instead, I would like to discuss support for a partial, user-defined workflow: a durable Space template that saves a Space’s layout while replacing its views with named placeholders (which I will refer to here as a "space template"). A space template is effectively a Space where the containers are placeholders.

Example
Here's a mockup of what a space template would look like (probably a JSON file; more on that later):

Space template
  workspace layout and modifiers
  container hierarchy and geometry
  slot: mail
  slot: terminal
  slot: editor

After a restart, the user would launch their applications and use a Lua script to bind live windows to template slots. The script would own the matching policy (for example, matching Firefox and terminal windows by predictable app IDs and titles) then ask Scroll to apply the template using the existing Space-loading behavior.

This keeps application/session logic outside the compositor. Different users have different applications and restoration mechanisms, and Scroll would not need to guess how a particular window should be recreated or identified.

Possible API shape
scrollmsg -t get_spaces already exposes a saved Space’s hierarchy and live-view metadata, but it does not include enough state to faithfully export its layout. A template would need at least:

• tiling/floating hierarchy and child order;
• container layout, geometry, fractional sizes, and content scale;
• workspace layout and scroller modifiers;
• focused child / focused slot;
• stable slot names for leaf containers;
• optional view hints (app_id, class, title) for user scripts.

{
  "version": 1,
  "name": "work",
  "workspace": {
    "layout": "horizontal",
    "scroller": {
      "mode": "horizontal",
      "insert": "after",
      "reorder": "auto"
    }
  },
  "tiling": [
    {
      "layout": "horizontal",
      "children": [
        {
          "slot": "mail",
          "size": { "width_fraction": 0.5, "height_fraction": 1.0 },
          "view_hint": {
            "app_id": "firefox",
            "title": "firefox@email@layout1"
          }
        },
        {
          "slot": "terminal",
          "size": { "width_fraction": 0.5, "height_fraction": 1.0 },
          "view_hint": {
            "app_id": "kitty",
            "title": "~/work"
          }
        }
      ]
    }
  ],
  "floating": [],
  "focused_slot": "mail"
}

The exact JSON schema is not the important part; slot is. Unlike con_id or PID, a slot is durable and can be explicitly bound to a newly created live view.

Implementation questions
One option would be to enrich get_spaces so scripts can export the current in-memory Space. Another would be a dedicated, versioned template export/import IPC API, leaving get_spaces as a description of live saved Spaces. I think this might be better long-term, otherwise every script would require the user to query all spaces every time they want to query one or more spaces (via inspecting the IPC json with jq or some other json parser).

Either way, a Lua-facing binding API would be needed, conceptually:

I think loading should require every required slot to be bound by default, avoiding a partially applied or destructive restore. Matching logic, launch order, retries, and application-specific restoration should remain entirely user-defined.

Would this be a useful direction for Spaces, and would a dedicated template API be preferable to extending get_spaces?

[dawsers]

This could be interesting, and if you want to implement it, probably the easiest way would be through a Lua script. If you want to try to do it, you would need some API support to read spaces information (there is already JSON support). I would be open to help you there: propose some Lua API functions you would like to have, and we can discuss them.

Moving from that to persistent sessions, like you said, would need some protocol support which doesn't fully exist yet.

[eghere]

Thanks! I agree that a LUA script is the best starting point for this feature; Lua can own persistence, application launching, and matching. Scroll would only need to expose enough of its current space implementation to serialize/apply it to newly selected views. So something like:

-- Return a Lua table describing an existing saved Space.
scroll.space_get(name) -> table|nil

-- Apply a template to workspace, substituting named slots with live views.
scroll.space_apply(workspace, template, bindings) -> boolean, error?

space_get() would expose the complete existing Space layout:

• tiling/floating hierarchy and child order;
• layout type;
• width/height fractions and geometry;
• floating placement;
• content scale;
• focused child / focused leaf;
• view metadata useful as export-time hints (app_id, class, title, etc.).

Lua could then add durable slot names to leaf nodes before writing the table with the existing JSON helpers.

local template = scroll.space_get("work")

-- Script assigns stable slot names before persisting JSON:
-- "mail", "terminal", "editor", etc.
write_template(template)

On restore, a user script would launch/wait for applications, use its own matching logic, and then provide some selected live views:

local bindings = {
    mail = mail_view,
    terminal = terminal_view,
    editor = editor_view,
}

local ok, err = scroll.space_apply(
    scroll.focused_workspace(),
    template,
    bindings
)

space_apply() would use the same non-destructive semantics as space load: move the bound views into the template’s saved hierarchy and leave unrelated views alone. It should validate that: each required slot is present, each view is mapped, and no view bound twice.

This keeps Scroll independent of application-specific session restoration. A script can match windows by title, app_id, parent process, environment, or whatever convention its user prefers so that Scroll doesn't have to.

What do you think?