Skip to content

docs(rfc): record the foldable layout's Phase 0 probe readings and test table - #33463

Open
jeeshofone wants to merge 1 commit into
kirodotdev:mainfrom
jeeshofone:docs/rfc-fold-phase0-table
Open

jeeshofone wants to merge 1 commit into
kirodotdev:mainfrom
jeeshofone:docs/rfc-fold-phase0-table

Conversation

@jeeshofone

@jeeshofone jeeshofone commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Put the foldable layout RFC's Phase 0 probe readings and test table into the document, so Phase 1 can start from measured fold signals.

The fold-aware layout RFC (docs/request-for-change/rfc-foldable-viewport-segments.md) says no Phase 1 code opens until its Phase 0 table is in the document, and the maintainer's sign-off on #29145 repeats that. The table was not there.

Why it matters

Phase 1 builds fold detection on what the browser reports. Without measured readings, that code would rest on guesses about which poses report a fold.

Not a goal

  • Any code change. This PR edits two Markdown files.
  • Changing the signed breakpoint rule, phases or goals. One new design rule is added for sign-off; see "What changed".
  • Split view. It was not reached on the simulator, so it is untested, not passed: its probe row and its test-table row both say so.

What changed (motivation → approach → change)

The RFC's Phase 0 section now holds two tables. The first records what the iPhone Duo simulator (Safari 27.2, both feature flags on) reports in six poses, in a Safari tab and as a Home Screen web app: posture, both segments media queries, window.viewport.segments and every viewport-segment-* env() value. The second gives one row per pose and window width with its expected layout, the fold signal behind it and how it is tested. That covers outer and inner displays, half-folded, split view, Home Screen web app, windows 639px to 768px wide with and without a fold, Reduce Motion and right-to-left.

The readings answer Open question 1: the two half-folded segments meet with no gap. A fully open inner display in portrait (669px) reports one segment, and half-folded in portrait reports two stacked segments, so under the signed rule both keep the phone form. In the web app the fold sits at 475.5px of an 867px viewport, so fold placement has to read the segments, not the viewport centre.

The "That bug is on main today" sentence in Continuity now links #29523, which fixed it. The front matter and the index row record the re-audit at 87247b9cdb.

The document also gains one design rule, under Design, "A reported fold and the touch-first phone rule": when the fold query matches two horizontal segments and the viewport is at least 640px wide, the two-pane form takes precedence over the touch-first phone rule from #30619, which left fold-aware layout to this RFC. A flat inner display at 951px, the inner display upright at 669px and every touch browser that reports no fold keep the phone form. The test table rows for those poses now say so.

@bolichen97, you signed the direction of #29145: please sign that precedence line, since it meets a merged rule. The RFC's status is unchanged by this PR; on main its front matter still reads status: draft and its first line reads "- Status: draft. Nothing is built."

Backwards compatibility

Compatible: documentation only.

Removes nothing from the design. Besides the two tables, the diff changes these lines:

  • Adds the section "A reported fold and the touch-first phone rule" (the rule above) and the 640px floor.
  • Rewrites the "Which poses switch" bullet so a mobile-mode touch browser keeps the phone form when flat.
  • Links fix(chat): keep the reader's row when the dashboard switches between desktop and phone #29523 from the "That bug is on main today" sentence.
  • Front matter: last-audited, audited-at, doc-pr: 29145 and tracking-issues: [29143].
  • The README index row moves its audit to 87247b9cdb and replaces "Acceptance requested from a maintainer; Phase 0 (a probe) runs first" with the Phase 0 status. The RFC stays draft, so acceptance is still pending.

Tests

Proof: not provable -- docs or config only

./scripts/docs-lint.sh and semgrep scan --config semgrep/ both pass on this head.

Manual verification

The readings come from a probe page on the iPhone Duo simulator that uses the dashboard's own viewport meta tag, opened in a Safari tab and from the Home Screen. Each pose was set with the simulator's fold and rotate controls with both flags on; a flags-off pass shows no API in any pose. Split view could not be entered (Device Hub's menus have no split control and the App Switcher shows one card per app), so it has no reading and no test result.

Related Issues

Part of #29143

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Re-dated for a fresh CI run after the repository sweep cancelled two re-runs of the previous run; content unchanged (tree identical).

@jeeshofone
jeeshofone requested review from a team and KiroCrewCaptain as code owners November 8, 2026 23:02
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 8, 2026
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ⏭️ skipped

Revision ba38298140af8b18b2dbdea085eaa794329c38be ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of ba38298140af8b18b2dbdea085eaa794329c38be via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

A docs-only change to a draft RFC: it records measured readings, and the one new precedence rule waits for a named maintainer's sign-off.

Notes

[DESIGN-REVIEWED] ba38298

Description read

[DESCRIPTION-READ] f43cd38e2df46bd3c0418e2266a1633e9e6948d76eb5f0626a754822c0b87aa6

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed ba38298140af8b18b2dbdea085eaa794329c38be via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ba38298

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed ba38298140af8b18b2dbdea085eaa794329c38be via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ba38298

@jeeshofone
jeeshofone force-pushed the docs/rfc-fold-phase0-table branch from dec640a to 7dd8a08 Compare November 9, 2026 02:27
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision ba38298140af8b18b2dbdea085eaa794329c38be touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 9, 2026
@jeeshofone
jeeshofone force-pushed the docs/rfc-fold-phase0-table branch from 7dd8a08 to d3d0d0b Compare November 9, 2026 04:01
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 9, 2026
@jeeshofone
jeeshofone force-pushed the docs/rfc-fold-phase0-table branch from d3d0d0b to b57cac4 Compare November 9, 2026 06:08
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 9, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, but it is held at tier 2: design-doc-gate: D.

Docs-only update to a draft RFC that records Phase 0 simulator probe readings and a test table, answers Open question 1, links the fix for the virtualizer bug, and proposes one precedence rule (a reported fold beats the #30619 touch-first phone rule at ≥640px), with maintainer sign-off explicitly requested. Verified at head: nothing under website/src reads the fold APIs, so the "Nothing built" index row is correct, and the touch-first rule the new section cites exists as described (touchLayoutForm.ts, the md: variant keyed on data-layout-form, narrow-viewport.md). The status stays draft, split view is marked unmeasured rather than passed, and CI and all lanes are green. No code, state or trust boundary changes.

Tier: 2, held for a person: design-doc-gate: D.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit ba38298140 · 78 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Nov 13, 2026
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Re the code change approver note (comment): the description now matches the diff. It no longer says the diff only adds rows and rewords one sentence, or that the signed design is unchanged. It names everything the commit changes beyond the two tables:

The precedence rule itself still needs a maintainer to sign it.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 13, 2026
@jeeshofone
jeeshofone force-pushed the docs/rfc-fold-phase0-table branch from f4ab380 to edab496 Compare November 13, 2026 12:06
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 13, 2026
@jeeshofone
jeeshofone force-pushed the docs/rfc-fold-phase0-table branch from edab496 to 293dbe3 Compare November 13, 2026 19:29
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 13, 2026
@jeeshofone
jeeshofone force-pushed the docs/rfc-fold-phase0-table branch from 293dbe3 to d0d38f9 Compare November 14, 2026 02:27
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 14, 2026
@jeeshofone

Copy link
Copy Markdown
Contributor Author

Rebased onto current main (eecf4c1) to pick up #39262, which fixes the test_bare_session_handle_guard failure (#39261) that the previous base predated. Docs-only content is unchanged.

@jeeshofone

Copy link
Copy Markdown
Contributor Author

Rebased onto current main (89438fd) to clear a conflict in the docs/request-for-change/README.md index row; the RFC text is unchanged.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants