Add LAYOUT_CONFIG_FIELDS step to the make-widget checklist

A new widget type shipping without an entry there fails silently --
no error, no test failure, it just saves/applies with an empty config
forever. Caught for real on the weather widget (37d57a1); adding the
step and a matching test-pattern bullet so the next widget type doesn't
repeat it.
This commit is contained in:
2026-07-28 15:17:43 +00:00
parent 37d57a1f88
commit bcea090e73
+18 -1
View File
@@ -1,6 +1,6 @@
---
name: make-widget
description: Scaffold a new widget type for the espresso_frame server (the ~13-file checklist a widget type touches -- config table, grid footprint, render module, registry, migration, config-save + endpoints, dialog template + JS, script tag, WIDGET_LABELS, docs, tests). Use when asked to add a new widget type to a frame's panel (e.g. "add a text widget", "add an RSS widget", "add a weather-only widget").
description: Scaffold a new widget type for the espresso_frame server (the ~14-file checklist a widget type touches -- config table, grid footprint, render module, registry, migration, config-save + endpoints, dialog template + JS, script tag, WIDGET_LABELS, docs, saved-layout config allowlist, tests). Use when asked to add a new widget type to a frame's panel (e.g. "add a text widget", "add an RSS widget", "add a weather-only widget").
---
Adding a widget type is a very consistent, repeated pattern in this
@@ -114,6 +114,16 @@ Pick your template accordingly:
`MIN_FOOTPRINT` prose line, the `app/widgets/` module list. This is
the project's own "start here" doc per `CLAUDE.md` -- don't ship a
widget without it staying accurate.
14. **`app/routers/api_layouts.py`** -- add a `"<type>": (...)` entry to
`LAYOUT_CONFIG_FIELDS` listing the config columns that are an
authored *setting* (as opposed to runtime/cache state like a fetch
cache or queue position, which a saved layout deliberately leaves
out -- see the dict's own comment). Skipping this doesn't error or
warn anywhere: the widget just silently saves/applies with an empty
`{}` config forever, resetting to defaults on every layout apply or
hold-to-cycle. This actually shipped missing for the weather widget
-- caught only because a user noticed layout-cycling kept resetting
its city/mode.
## Tests (`server/tests/`)
@@ -138,6 +148,13 @@ Pick your template accordingly:
- Any pure-logic helper module (decoding, parsing -- like
`app/image_upload.py`) gets its own `test_<module>.py`: no HTTP, no
DB, just the function.
- `test_saved_layouts.py` -- a `test_save_and_apply_round_trip_<type>_settings`
test: set every field the new `LAYOUT_CONFIG_FIELDS` entry lists,
save a layout, assert the `SavedLayoutWidget.config` snapshot has them
all, delete the frame's widgets, apply the layout back, assert the
new widget's config matches -- and that any runtime/cache field
(`checked_at`, a fetch cache, a queue) was *not* carried over. See
`test_save_and_apply_round_trip_weather_settings` for the pattern.
Run the full suite before calling it done: