Skip to content

Phase 31 slice F: overlay rules - #250

Merged
vicmaster merged 5 commits into
masterfrom
phase-31-slice-f
Nov 15, 2026
Merged

vicmaster merged 5 commits into
masterfrom
phase-31-slice-f

Conversation

@vicmaster

Copy link
Copy Markdown
Owner

Slice F of Phase 31 (docs/specs/PHASE-31-SPEC.md, FR-F1): the overlay rules. A new desktop-app rule, desktop-app-overlay, flags overlays that cannot work as drawn. The spec's "Slice F — contracts pinned before build" block (S8, M1 to M8) records the contracts. The "Slice F — as built" block (N1 to N4) records the corrections found while building and every fix from verification.

What changes

  • Warnings (block presenting on a desktop-app canvas):
    • a second modal on one canvas
    • a tooltip with children, which never render
    • inside a modal, a detected table of more than ten body rows (a header row does not count)
    • inside a modal, a frame with overflow: "auto" that renders wider than the modal or scrolls sideways
    • an overlay whose box leaves the viewport (the root's size, else the window's)
    • a popover or menu on a canvas that holds a modal or a drawer with scrim: true (spec change S8). Popovers and menus stack at 400, under the scrim at 500, so they show dimmed behind the dialog.
  • Infos:
    • a second toast
    • a toast with tone: "danger" (put the error inline or in a banner)
    • an anchor that names no node, or a node that is not a clickable primitive or control
  • "Inside a modal" means the modal is the node's nearest overlay ancestor. A popover inside a modal is lifted out of it, so a table in that popover is the popover's, not the modal's.
  • Fast and detailed mode.
    • Detailed mode checks every rendered overlay's box, with 1px of tolerance.
    • Fast mode boxes only what authored numbers decide: a popover or menu with numeric x, y, width and height, and a placed modal's left, right and top edges. Tooltips and toasts size to their text and drawers are pinned right, so they are left to detailed mode.
    • A modal wider than the viewport less 32px warns in both modes, since the render squeezes it.
  • Desktop-app only. Web and mobile canvases never run the rule.
  • Agent surfaces updated: the server instructions, the overlay gotcha, the batch_design overlay section, the canvas_evaluate docstring, the rule and overlay sections of docs/GUIDELINES.md, the README rule table and overlay paragraph, and VISION.md.

Decisions worth a look

  1. Spec change S8, approved before the build. Slice E left a menu or popover under a modal's scrim as a known trap. It now warns, and so does one under a drawer that has scrim: true, for the same reason.
  2. A header row does not count toward the ten rows. This follows your answer before the build. A headerless table of plain-text rows still has its first row read as a header by the shared isHeaderRow test, so eleven such rows count as ten.
  3. The renderer shrinks a bare px width to its parent (max-width: 100%). So fast mode reads only a minWidth, or a width whose maxWidth lets it stay wider, as wider than a modal. maxWidth is read as CSS reads it: px, % and vw cap it; "none" and a negative value leave it uncapped; any other unit is read as the parent. The pinned contract compared the bare width, and N1 records the correction.
  4. Fast mode boxes less than the contract said (N4). The contract had fast mode box every overlay with authored x, y, width and height. A tooltip and a toast ignore an authored width, and a modal's height is its content. So fast mode warned on clean screens. A test now runs ten scenes in both modes and asserts the verdicts agree.
  5. Accepted as specced:
    • Fast mode has no tolerance and detailed mode has 1px, so an overlay exactly 1px past an edge warns in fast mode only.
    • Two overlays sharing an id keep only the later rect.

Testing

  • New test-desktop-app-overlay.ts (fast) covers:
    • every warning and info, each with a twin that must stay silent
    • instances, anchors and root coordinates
    • viewport fallbacks and exact-fit edges
    • injected rects for the detailed fallbacks
    • severities and categories
    • silence on web and mobile
    • the two acceptance stand-ins built from list-detail-app (confirm-delete and comment-open), which raise no blocking finding of any rule, plus a failing twin of each
  • New test-desktop-app-overlay-detailed.ts (Chrome) covers:
    • rendered boxes and sideways scrolling
    • what fast mode leaves to detailed mode
    • fast/detailed agreement on ten scenes
    • the stand-ins in detailed mode
  • Verification, first round: four agents on 64b0856.
    • Spec conformance confirmed every clause and found two defects. A modal authored inside a table-shaped frame never had its body tables checked. A scroller with a non-numeric maxWidth was a false positive in fast mode.
    • Mutation testing ran 112 mutants. The survivors were boundary, severity, category and fallback gaps, and every one now has a test that kills it.
    • Docs steward found the server instructions never named the rule.
    • Cold reader got all ten tasks right from the guideline alone and flagged five unclear sentences. All five are rewritten.
    • Each fix was proved red on 64b0856 and green after, with its keep-cases unchanged.
  • Verification, second round (on the fixes, a94c8c9): one agent confirmed the fixes hold and add no crash path. It found that fast boxes still used sizes the render ignores. That fix (N4) was proved red on a94c8c9 and green on e9ce434; no agent re-verified it.
  • npm run test:full: 132/132 on e9ce434. The last commit only corrects two comments; npm test gives 88/88 on it, and the detailed overlay test passes.

@vicmaster
vicmaster merged commit ff102c3 into master Nov 15, 2026
3 checks passed
@vicmaster
vicmaster deleted the phase-31-slice-f branch November 15, 2026 23:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant