SwayFX Mosaic

SwayFX Mosaic is an experimental SwayFX variant that adds a native Mosaic / Spatial Canvas tiling layout.

The goal is not to replace SwayFX, reimplement tiling in userspace, or turn the desktop into a floating-window canvas. Mosaic stays inside the compositor and keeps real Sway containers, workspaces, IPC, fullscreen, floating windows and scratchpad semantics.

Status: active development. The compositor is not installed as the daily SwayFX session yet.

Why Mosaic?

Classic tiling is constrained by the physical viewport. Mosaic introduces a logical canvas made of horizontal rows that may extend beyond the visible output.

Workspace
└── Mosaic Canvas
    ├── Row 0: [A][B][C][D]...
    ├── Row 1: [E][F][G]...
    └── ...

Each row owns its viewport position and last focused container. The compositor remains the source of truth for order, geometry, focus and scrolling.

Core rules

• real tiled Sway containers; no floating-window simulation;
• Mosaic is opt-in per workspace;
• standard Sway/SwayFX layouts remain available;
• workspaces continue to exist normally;
• Mosaic state lives in the compositor, not in QuickShell;
• the standard swayfx package must remain untouched and independently updatable;
• the Mosaic package installs a separate /usr/bin/swayfx-mosaic binary;
• our production artifact is a minimal, reviewable patch on a pinned SwayFX upstream revision.

Package model

swayfx
└── /usr/bin/sway

swayfx-mosaic
└── /usr/bin/swayfx-mosaic

swayfx-mosaic must not declare provides, conflicts or replaces against SwayFX. An upstream SwayFX update must never be blocked by this project.

The Arch packaging path is intentionally patch-based:

pinned SwayFX upstream
        +
Mosaic patch set
        ↓
/usr/bin/swayfx-mosaic

See docs/ARCHITECTURE.md and docs/UPSTREAM.md.

Layout switching

The target desktop contract is:

Super + Alt + M  → Applications
Super + Alt + L  → Standard layout ↔ Mosaic

The compositor command is:

layout toggle mosaic

Each workspace remembers its previous standard layout, so a toggle behaves conceptually like:

tabbed → mosaic → tabbed
splith → mosaic → splith

The key binding itself belongs to the user's dotfiles, not to this package.

Current implementation

The current development tree contains the native Mosaic foundation and the first single-row viewport work:

• native L_MOSAIC layout;
• workspace-local Mosaic state;
• ordered Row 0 backed by real workspace->tiling containers;
• insertion after the active container;
• workspace-local previous-layout memory;
• layout toggle mosaic;
• logical scroll_x;
• first scene translation / single-row viewport implementation;
• IPC exposure through get_tree;
• model and headless compositor tests;
• Arch package staging limited to swayfx-mosaic.

Multi-row behavior, robust multi-output clipping, final sizing policy, camera animation and session restore integration are still development work.

Technical reports:

• STEP20A — native foundation
• STEP20B — first scrollable row

Development

Baseline:

meson setup build-baseline -Dwerror=false -Dsd-bus-provider=libsystemd
meson compile -C build-baseline

Mosaic build:

meson setup build-mosaic \
  -Dwerror=false \
  -Dsd-bus-provider=libsystemd \
  -Dmosaic-package=true \
  -Dprefix=/usr -Dbindir=bin \
  -Dswaybar=false -Dswaynag=false \
  -Dman-pages=disabled -Ddefault-wallpaper=false

meson compile -C build-mosaic
meson test -C build-mosaic --print-errorlogs
python tests/headless-ipc.py

See docs/DEVELOPMENT.md for the full workflow.

Repository layout

docs/       design, roadmap and validation reports
patches/    production delta against pinned SwayFX
tests/      Mosaic model and headless compositor tests
tooling/    patch/export maintenance helpers
PKGBUILD    coexistence-oriented Arch package

The full SwayFX source remains in the development tree for compositor work. The patch set is the reviewable production delta.

Upstream and license

SwayFX Mosaic is derived from SwayFX, itself based on Sway.

Current base:

• SwayFX tag 0.6;
• commit fd71a6bdc061bd633b488ae7b83e8a6981d22f86;
• Sway 1.12.0 base;
• wlroots 0.20 series;
• SceneFX 0.5 series.

The project keeps the upstream MIT license. See LICENSE and NOTICE.md.

Mirrors

Canonical development repository:

• Forgejo: https://git.labfytools.com/fy59/swayfx-mosaic

Public mirror:

• GitHub: https://github.com/labfytools/swayfx-mosaic