Improve Figma image projection and responsive layout

[chubes4]

Summary

• retain source image selectors on canonical core/image wrappers and project presentation to nested image elements without replaying relative source geometry
• allow Figma card content and featured sections to grow from real flow content
• stack unsafe desktop-only rows and preview-card collections on mobile without cross-axis wrapping or shrink collapse
• constrain mobile separators and pagination, emitting pagination as semantic navigation
• preserve inferred semantic-grid height floors while moving positioned content children into mobile flow
• constrain opaque nested component text clones to the mobile viewport content boundary

Fixes #662.

Root causes

Image declarations originally stopped at the canonical WordPress image wrapper, leaving the nested raster with incorrect presentation. Replaying every source declaration on that raster was also incorrect for relative geometry because it applied percentages twice.

The responsive failures came from desktop-only Figma exports whose source frames had no mobile variant. Generic fluid fallback rules stacked horizontal collections, but retained wrapping, shrinking, canvas coordinates, or fixed shared component widths could still collapse content or create overflow.

Verification

• cd figma-transformer && composer test
• git diff --check
• all Figma Transformer contract tests pass
• retained real-fixture standalone matrix covered 14 desktop/mobile comparisons across FSE Pilot Build Theme, Twenty Twenty-Five, and Fisiostetic
• before the final containment rule: 13/14 passed, with zero failed images, zero top-level overlaps, and zero collapsed nodes
• the only remaining failure was FSE Blog mobile: two opaque shared labels were 640px wide at left:24px, producing exactly 274px overflow in a 390px viewport
• the final rule caps those labels at calc(100vw - 48px) (342px at the tested viewport), placing their right edge at 366px; contract coverage verifies the rule is emitted for desktop-only responsive output

The full contract suite also covers:

• positioned versus flow image projection
• explicit img selector specificity and root-child images
• card intrinsic growth and non-shrinking mobile stacks
• form rows that stack without wrapping into columns
• text-only rows retaining their height floor
• inferred semantic grids retaining source height and releasing positioned children into mobile flow
• mobile separator and pagination containment

How to test

1. Run cd php-transformer && composer validate --strict && composer test.
2. Run cd ../figma-transformer && composer test.
3. Transform a desktop-only Figma export with figma-transformer/bin/figma-transformer <fixture.fig> --multi-page --output-dir=<output> using the configured Kiwi decoder.
4. Render generated routes at desktop and 390px mobile widths.
5. Confirm horizontal overflow, failed images, top-level overlaps, and collapsed content nodes are all zero.
6. Confirm source geometry remains on canonical core/image wrappers while positioned nested images fill their wrappers and flow images retain intrinsic sizing.

Compatibility

No public API or custom block-attribute changes. The behavior is implemented through generated author styles, semantic HTML emission, and generic responsive fallback policy.

AI assistance

Substantive implementation, test drafting, fixture diagnosis, and verification were performed with OpenCode using openai/gpt-5.6-sol. Chris Huber directed the work and remains responsible for the submitted changes.

[chubes4]

Browser verification update for c69e458e:

• Root cause: author stylesheet projection updated content but retained stale content_base64; SSI correctly decoded the stale declared payload.
• Repair: keep projected text/base64 payloads consistent and target canonical .wp-block-image > img with sufficient specificity.
• Fisiostetic nested image: 123.28 x 82.19, object-fit: fill before; 123.30 x 106.50, object-fit: cover after, exactly matching the generated figure/source box.
• Aligned full-page mismatch: 33.12% (2,330,394 / 7,036,160) before; 19.58% (1,377,921 / 7,036,160) after.
• Editability stayed green: 159/159 native blocks, zero core/html, 159/159 browser-validated blocks valid.
• composer test passes, including canonical/unit contracts, 244 parity fixtures, and package-install proof.

Reproduction uses SSI tools/run-fig-fixture-e2e.mjs with the Fisiostetic .fig, this branch as --blocks-engine-php-transformer-path, WP Codebox 0.12.29, one fixture/batch, and browser visual parity enabled.

AI assistance: OpenCode with openai/gpt-5.6-sol, directed by Chris Huber.

[chubes4]

Post-fix Lab browser verification is currently blocked before candidate startup by a stale shared WordPress archive cache lock, not by this branch. Both the primary and recovery recipe-run failed in preview:loading-wordpress with wp-codebox-playground-startup-asset-unavailable for /home/chubes/.wordpress-playground/7.0.2.zip.lock; no visual summary was produced. Tracked upstream in Automattic/wp-codebox#1941: Automattic/wp-codebox#1941

Local verification for commit 82f507ca remains green: full composer test, including 244 parity fixtures and the fixed/percentage image projection regression.

[chubes4]

Correction to the Lab blocker note above: direct inspection shows homeboy-lab is running WP Codebox commit 795028fc, before merged cache-lease recovery #1936 (7befb071) and staged-binary repair #1939. The retained owner lease is explicitly expired (expiresAt: 1970-01-01T00:00:00.000Z), and current WP Codebox main already reclaims it. Browser verification therefore requires an operator-approved Lab WP Codebox upgrade; the lock was not manually removed. See the corrected diagnosis on Automattic/wp-codebox#1941 (comment).

The solved-site promotion check also failed independently because SSI could not compile fixture 15-saas: its existing CSS data URI was reported as unresolved local reference %3Csvg, so no static front page was created. The branch-specific Composer, visual-tool, and site-plan checks all pass; this promotion result does not reach the image geometry behavior.

[chubes4]

Stacked Lab acceptance after upgrading homeboy-lab WP Codebox to a9edf319:

• Candidate stack: this branch at c7040685 + Keep positioned media layouts out of galleries #669 gallery safety rebased on top
• Fisiostetic mismatch: 11.1467% -> 7.6012%
• Mismatch pixels: 784,297 -> 534,833 (249,464 removed)
• Hero image hotspot: 182,605 -> 0
• Map hotspot: 416,466 -> 362,084
• Source/candidate dimensions: exact 1280x5497
• Source images: 26/26 loaded; candidate images: 17/17 loaded
• Capture readiness: high confidence

Retained evidence: /home/chubes/Developer/_lab_workspaces/blocks-engine-validate-663-669-stack-c360660f2849-b9083eaa-54a0-47d9-be29-3d98c1909da8-1784659425541639000/artifacts-fisiostetic-stacked-v16.

This validates the structural boundary: source geometry remains on canonical wrappers, and only out-of-flow source images receive nested fill geometry.