refactor(homarr): extract layout packing to filter plugin

roles/homarr/README.md

@@ -13,7 +13,7 @@ and customizable application tiles.
   - a local admin user with bcrypt-hashed password
   - OIDC and credentials admin groups with full permissions
   - application tiles defined in `homarr_apps`, auto-laid-out across all
-    three screen sizes
+    three screen sizes via the bundled `homarr_compute_layouts` filter
 - Skips the onboarding wizard so the instance is usable right after deploy
 - Restarts the container via handler when the seed or compose file changes
 
@@ -100,6 +100,53 @@ homarr_apps:
     width: 2
 ```
 
+## Layout filter plugin
+
+The grid-packing algorithm that places tiles on the desktop, tablet
+and mobile layouts lives in `filter_plugins/homarr_layout.py` rather
+than inside the Jinja seed template. This keeps the SQL template
+readable and lets the algorithm be unit-tested in isolation.
+
+The filter is invoked once from `tasks/main.yml`:
+
+```yaml
+- name: Compute Homarr app layouts
+  ansible.builtin.set_fact:
+    homarr_layout: "{{ homarr_apps | homarr_compute_layouts }}"
+```
+
+This produces a `homarr_layout` fact with two keys, both consumed by
+`templates/homarr_seed.sql.j2`:
+
+| Key | Shape | Purpose |
+|---|---|---|
+| `apps` | list, same order as `homarr_apps` | each entry enriched with `desktop`, `tablet`, `mobile` sub-dicts of `{x, y, w, h}` |
+| `section_height` | dict with `desktop`, `tablet`, `mobile` | minimum height of the parent section so all tiles fit |
+
+The filter signature accepts custom column counts if Homarr ever
+changes the breakpoint widths:
+
+```jinja
+{{ homarr_apps | homarr_compute_layouts(desktop_cols=12, tablet_cols=8, mobile_cols=4) }}
+```
+
+To debug a layout without running the full deploy, run the play with
+`-vv` — the `Show computed app layouts` task dumps the full
+`homarr_layout` fact.
+
+### Running the filter tests
+
+The filter is covered by unit tests in
+`filter_plugins/tests/test_homarr_layout.py`:
+
+```bash
+pip install pytest ansible-core
+pytest filter_plugins/tests/
+```
+
+15 tests cover packing, width clamping, height/section-height,
+input validation and custom grid sizes.
+
 ## First login
 
 After the role completes, log in at `{{ homarr_base_url }}` with: