Validate a full composed screen (one commit, one revision) against the live instance #201

New issue

Closed

opened 2026-09-14 23:11:53 +00:00 by david · 1 comment

david commented

2026-09-14 23:11:53 +00:00

Owner

Summary

Validate composition against the live instance by building one realistic screen — a shell frame with a cards row, progress bars and text — in a single commit, then confirming in the Penpot UI that the result is a design a human can keep working in: named layers, real text objects, fills linked to library assets, and an auto-layout frame that reflows.

Background

Depends on: #200

Each primitive has been validated in isolation; this gate validates that they compose, and that the "editable" property the feature is built around actually holds. It is also the first end-to-end exercise of the batched-commit architecture: many add-obj changes in one update-file call, applying atomically as exactly one revision, with the server maintaining parent shapes arrays as children are added.

The specific properties being proven, in the order of how easy they are to get subtly wrong:

One screen = one revision. A row of cards plus their children staged together must not produce partial screens or a multi-step revision history.
Linked styling. Editing one library colour must restyle the screen.
Real objects. Text must be a text object; nothing may be flattened into an image or path.
Working layout. The frame must genuinely be a layout frame: resizing a child reflows siblings.

Required environment: PENPOT_URL, PENPOT_TOKEN, and the scratch project with the colour/typography assets created in the earlier validation steps.

Documentation Required

A separate process downloads these into the listed folders before this issue is implemented. Check the folders for the actual reference material before starting.

docs/reference/penpot-api/

https://raw.githubusercontent.com/penpot/penpot/2.17.2/common/src/app/common/types/shape.cljc — shape/layout fields, for interpreting anything the UI shows differently from what was staged.
https://raw.githubusercontent.com/penpot/penpot/2.17.2/common/src/app/common/types/shape_tree.cljc — how parents/children and shapes arrays are maintained (used to confirm the server-side wiring).
<PENPOT_URL>/api/main/doc/openapi.json — update-file on the running version, if a failure needs isolating with curl below the extension.
https://help.penpot.app/user-guide/design-systems/layout/ — what the Layout panel is expected to show, for the reflow check.
https://help.penpot.app/user-guide/design-systems/assets/ — what a "linked" swatch/text style looks like in the UI, for the linked-fill check.

docs/reference/pi-coding-agent/

https://pi.dev/docs/latest/extensions — /reload and tool output capture for the evidence below.

Implementation Details

Build the screen described below using only the composition primitives (penpot_add_frame, penpot_add_rect, penpot_add_text, penpot_add_image), then run the checks. Where a check fails, fix the offending primitive in this step and repeat — a milestone does not advance on an unvalidated predecessor.

The screen (a plausible DESIGN.md dashboard section; adapt names to the scratch file's actual assets):

a screen frame at the page root, layout: flex, column, gap 24, padding 32, filled with a background library colour;
a header frame, layout: flex, row, gap 16, align_items: center, containing a title text (library typography h2) and a subtitle text (h3/body);
a cards frame, layout: flex, row, gap 16, containing three card frames, each containing a rect (linked fill), a title text and a body text;
a progress frame containing three progress-bar constructions (a track rect plus a filled-value rect, or a single rect if that is what the primitives support cleanly) — if the primitives cannot express a partial bar cleanly, record the gap rather than hacking it.

Checks and evidence:

Stage everything, then commit once. Record the file's revn before and after; the advance must be exactly one. Confirm via penpot_get_file that every staged shape id exists.
Reload the file in the Penpot UI and confirm the layers are named as requested in the Layers panel, and that the composition matches the intended geometry.
Select the title text: it must be a text object with editable content — not an image, not a group of paths.
Confirm the card rects' fills show as linked swatches. Edit one referenced colour asset's hex in the UI, reload the screen, and confirm every shape using that asset changed.
Confirm the cards frame is a real layout frame: in the UI, select a card and resize it; confirm the sibling cards / the frame's contents reflow and the layout panel reports gap and padding as staged.
Confirm the server maintained each parent frame's shapes array without any follow-up mod-obj from the extension (check by reading the file and comparing child lists).

Record in extensions/penpot/findings.md under "Composed screen": the staged change count, revn before/after, the per-check outcome, UI screenshots/observations where useful, and anything that did not come out well — including any construction the primitives could not express (e.g. a partial progress bar). Do not phrase a gap as a success.

Acceptance Criteria

A screen of at least 15 staged shapes commits in one update-file call, with the file's revn advancing exactly once.
Every staged shape id is present in the file after the commit.
Layers in the Penpot UI are named as requested.
The title/subtitle/card text layers are real, editable text objects.
Card fills are visibly linked to library colours, and editing the library colour restyles the screen after reload.
The cards frame reflows when a child is resized in the UI, and the layout panel shows the staged gap and padding.
Parent frames' shapes arrays are correct without any follow-up mod-obj from the extension.
extensions/penpot/findings.md records the evidence for every check plus every construction the primitives could not express.
Any primitive defect found has been fixed in code, not merely noted.

Test Plan

Manual, against the live instance:

# in pi
/reload
# penpot_authorize_target(file_id)
# penpot_get_file(file_id)            -> record revn before
# penpot_add_frame / penpot_add_rect / penpot_add_text ... (the screen above)
# penpot_commit(file_id)              -> expect success
# penpot_get_file(file_id)            -> record revn after; expect exactly +1

Then, in the Penpot UI:

Reload the file; inspect the Layers panel for names and the canvas for geometry.
Select a text layer and type into it to prove it is real text.
Edit a referenced colour asset; reload; confirm the screen followed.
Resize a card child and confirm reflow.

## Summary Validate composition against the live instance by building one realistic screen — a shell frame with a cards row, progress bars and text — in a **single commit**, then confirming in the Penpot UI that the result is a design a human can keep working in: named layers, real text objects, fills linked to library assets, and an auto-layout frame that reflows. ## Background **Depends on:** #200 Each primitive has been validated in isolation; this gate validates that they compose, and that the "editable" property the feature is built around actually holds. It is also the first end-to-end exercise of the batched-commit architecture: many `add-obj` changes in **one** `update-file` call, applying atomically as exactly one revision, with the server maintaining parent `shapes` arrays as children are added. The specific properties being proven, in the order of how easy they are to get subtly wrong: 1. **One screen = one revision.** A row of cards plus their children staged together must not produce partial screens or a multi-step revision history. 2. **Linked styling.** Editing one library colour must restyle the screen. 3. **Real objects.** Text must be a text object; nothing may be flattened into an image or path. 4. **Working layout.** The frame must genuinely be a layout frame: resizing a child reflows siblings. Required environment: `PENPOT_URL`, `PENPOT_TOKEN`, and the scratch project with the colour/typography assets created in the earlier validation steps. ## Documentation Required A separate process downloads these into the listed folders before this issue is implemented. Check the folders for the actual reference material before starting. **`docs/reference/penpot-api/`** - https://raw.githubusercontent.com/penpot/penpot/2.17.2/common/src/app/common/types/shape.cljc — shape/layout fields, for interpreting anything the UI shows differently from what was staged. - https://raw.githubusercontent.com/penpot/penpot/2.17.2/common/src/app/common/types/shape_tree.cljc — how parents/children and `shapes` arrays are maintained (used to confirm the server-side wiring). - `<PENPOT_URL>/api/main/doc/openapi.json` — `update-file` on the running version, if a failure needs isolating with `curl` below the extension. - https://help.penpot.app/user-guide/design-systems/layout/ — what the Layout panel is expected to show, for the reflow check. - https://help.penpot.app/user-guide/design-systems/assets/ — what a "linked" swatch/text style looks like in the UI, for the linked-fill check. **`docs/reference/pi-coding-agent/`** - https://pi.dev/docs/latest/extensions — `/reload` and tool output capture for the evidence below. ## Implementation Details Build the screen described below using only the composition primitives (`penpot_add_frame`, `penpot_add_rect`, `penpot_add_text`, `penpot_add_image`), then run the checks. Where a check fails, fix the offending primitive in this step and repeat — a milestone does not advance on an unvalidated predecessor. **The screen** (a plausible `DESIGN.md` dashboard section; adapt names to the scratch file's actual assets): - a `screen` frame at the page root, `layout: flex`, `column`, gap 24, padding 32, filled with a background library colour; - a `header` frame, `layout: flex`, `row`, gap 16, `align_items: center`, containing a title text (library typography `h2`) and a subtitle text (`h3`/body); - a `cards` frame, `layout: flex`, `row`, gap 16, containing three `card` frames, each containing a rect (linked fill), a title text and a body text; - a `progress` frame containing three progress-bar constructions (a track rect plus a filled-value rect, or a single rect if that is what the primitives support cleanly) — if the primitives cannot express a partial bar cleanly, record the gap rather than hacking it. **Checks and evidence:** 1. Stage everything, then commit **once**. Record the file's `revn` before and after; the advance must be exactly one. Confirm via `penpot_get_file` that every staged shape id exists. 2. Reload the file in the Penpot UI and confirm the layers are named as requested in the Layers panel, and that the composition matches the intended geometry. 3. Select the title text: it must be a **text** object with editable content — not an image, not a group of paths. 4. Confirm the card rects' fills show as **linked** swatches. Edit one referenced colour asset's hex in the UI, reload the screen, and confirm every shape using that asset changed. 5. Confirm the `cards` frame is a real layout frame: in the UI, select a card and resize it; confirm the sibling cards / the frame's contents reflow and the layout panel reports gap and padding as staged. 6. Confirm the server maintained each parent frame's `shapes` array without any follow-up `mod-obj` from the extension (check by reading the file and comparing child lists). Record in `extensions/penpot/findings.md` under "Composed screen": the staged change count, `revn` before/after, the per-check outcome, UI screenshots/observations where useful, and **anything that did not come out well** — including any construction the primitives could not express (e.g. a partial progress bar). Do not phrase a gap as a success. ## Acceptance Criteria - [ ] A screen of at least 15 staged shapes commits in **one** `update-file` call, with the file's `revn` advancing exactly once. - [ ] Every staged shape id is present in the file after the commit. - [ ] Layers in the Penpot UI are named as requested. - [ ] The title/subtitle/card text layers are real, editable text objects. - [ ] Card fills are visibly **linked** to library colours, and editing the library colour restyles the screen after reload. - [ ] The cards frame reflows when a child is resized in the UI, and the layout panel shows the staged gap and padding. - [ ] Parent frames' `shapes` arrays are correct without any follow-up `mod-obj` from the extension. - [ ] `extensions/penpot/findings.md` records the evidence for every check plus every construction the primitives could not express. - [ ] Any primitive defect found has been fixed in code, not merely noted. ## Test Plan Manual, against the live instance: ```bash # in pi /reload # penpot_authorize_target(file_id) # penpot_get_file(file_id) -> record revn before # penpot_add_frame / penpot_add_rect / penpot_add_text ... (the screen above) # penpot_commit(file_id) -> expect success # penpot_get_file(file_id) -> record revn after; expect exactly +1 ``` Then, in the Penpot UI: 1. Reload the file; inspect the Layers panel for names and the canvas for geometry. 2. Select a text layer and type into it to prove it is real text. 3. Edit a referenced colour asset; reload; confirm the screen followed. 4. Resize a card child and confirm reflow.

david added this to the Penpot: M3 - Composition primitives milestone

2026-09-14 23:11:53 +00:00

david added the

feature

label

2026-09-14 23:11:53 +00:00

david referenced this issue

2026-09-14 23:14:25 +00:00

Add the image-to-design workflow to skills/penpot/SKILL.md #212

david referenced this issue from a pull request that will close it,

2026-09-15 04:01:35 +00:00

issue-201: Validate a full composed screen (one commit, one revision) against the live instance #234