Skip to content

The stage's utility area: revision chips and playback float over the stage - #58

Merged
agorischek merged 23 commits into
mainfrom
utility-area
Nov 21, 2026
Merged

agorischek merged 23 commits into
mainfrom
utility-area

Conversation

@agorischek

@agorischek agorischek commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

The stage's utility area: the third bar above the stage (each pane's label band in Side by side and Swipe, the playback row in Animated) becomes room floating over the stage's top edge, inset from its sides and as wide as it needs, so the viewer never stacks three full-width bars. Design note: docs/design/utility-area.md.

First of a stack: #58 → #65 (one-row toolbar, the stage's floating foot) → #77 (the pinnable projections pane).

What it does

  • Side by side and Swipe: the revisions' labels are chips on the stage. The before chip sits at its pane's top left and the after chip at its pane's top right (in columns and in Swipe; stacked panes keep both at the left), 12 px from the outer edge. Swipe keeps each chip to its half of the stage, so the two never meet at the divider.
  • Chip style: 28 px tall, 10 px of padding, in the playback bar's own fill, edge, corners and text (--ph-utility-*): the revision's name in mono at regular weight in the bar's muted text colour, then its commit subject one step more muted. The age is in the tooltip. Text is centred by cap height (text-box: trim-both cap alphabetic), and chips land on whole pixels.
  • Insets: chips and the bar sit 12 px from the stage's top and sides, the renderers' own content inset, so their edges line up with the tables and cards under them.
  • Animated, and the table and text views: playback floats in a centred bar at most 560 px wide; below 440 px it moves the steps and percent into its overflow. In a stage laid out in its page, the bar is sticky below the host's stuck toolbar (--ph-stage-sticky-top) and stops at the stage's end. The toolbar keeps one row; the title bar keeps its own row, per Centre the mode and scope switches in the toolbar; playback on a row of its own #25.
  • The stage runs under the area, and content panned or scrolled up shows around it and behind it.

How renderers keep clear: a new optional layout token, stage-cover

  • The stage measures what it overlays on each frame, in the frame's own coordinates, and sends the rectangles (x y width height, …). Beside them it sends stage-inset-top, the band they take. The host decides the cover, never the content, so there's no feedback loop.
  • Content that scrolls (tables, ContentView, pk-stage) pads its top by the band, as it already did under chips, and scrolls under it.
  • Fitted canvases (the kit's graph canvas, dependency injection) use the kit's new useCoveredPadding. It moves the top down only where the fitted, centred drawing would reach a rectangle, so a flat graph doesn't move at all. A view that opens scrolled, at the text floor, keeps its first row below the band.
  • A new cover is fitted to at once: nothing zooms, scales or slides on a mode switch. New chips and bars fade in over 120 ms, and not at all under reduced motion.
  • The area comes first in the DOM, so Tab reaches playback before the frames under it.

API: ProjectionStage's utility prop, the default UI's utilityArea, and the Inspector's utilityArea. The viewer page always turns it on.

Also

Tests

  • Kit unit test: parseStageCover and coveredTop, covering a flat graph, a tall graph against the chip and the bar, and a stage offset in its frame.
  • Inspector unit test: an abbreviated-hash label.
  • pane-labels.spec.ts: each frame's stage-cover matches its chips (both chips in swipe), the after chip at its pane's right, the utility bar's 12 px inset, whole-pixel centring and tokens, with no node under it, with and without fill; the sticky bar.
  • Run locally: chromium-desktop for that spec, check --fast, and the narrow unit tests. CI runs the rest.

Screenshots (DI hero demo, 630237f3 → 6af8d471, projections view screenshot --page). Taken before the chips took the bar's muted regular-weight text and the after chip moved right; #65 has current ones.

Side by side Animated Swipe
Light, 1280 light, wide, side by side light, wide, animated light, wide, swipe
Dark, 1280 dark, wide, side by side dark, wide, animated dark, wide, swipe
Light, 640 light, narrow, side by side light, narrow, animated light, narrow, swipe
Dark, 640 dark, narrow, side by side dark, narrow, animated dark, narrow, swipe

Tables (API renderer, Side by side) and playback over tables (database renderer, Animated):

API, 1280 API, 640 Database, 1280 Database, 640
Light API tables, light, 1280 API tables, light, 640 database tables under the playback bar, light, 1280 database tables under the playback bar, light, 640
Dark API tables, dark, 1280 API tables, dark, 640 database tables under the playback bar, dark, 1280 database tables under the playback bar, dark, 640

Open questions (also in the note): whether stage-cover belongs in the renderer environment rather than in theme tokens, and whether the bar should carry the revisions' names beside the slider.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Copilot was unable to run its full agentic suite in this review.

Copilot review overview

2 open issues
What changed in this PR

Adds a “utility area” that can float labels/playback over the stage and introduces a new stage-cover theme token so renderers (especially fitted canvases) can keep clear of host overlays precisely, with easing when the cover changes.

Changes:

  • Introduces stage-cover token plumbing (host measures overlays → tokens → renderer kit parsing + context).
  • Adds utility-area UI (floating playback/labels) and host support for enabling/disabling it via URL/options.
  • Updates renderer-kit layout logic/CSS and adds tests to ensure fitted drawings avoid only the relevant covered regions.
File Description
tools/​storybook/​harness/​host/​core.tsx Adds a Storybook query param to render a utility overlay into ProjectionStage.
packages/​renderers/​sdk/​src/​tokens.ts Documents stage-cover and adds it to optionalThemeTokenNames.
packages/​renderers/​kit/​test/​layout.test.mjs Adds tests for parseStageCover and coveredTop behavior.
packages/​renderers/​kit/​styles/​root.css Adds cover-change easing transitions (data-cover-easing).
packages/​renderers/​kit/​styles/​graph.css Uses --pk-fit-top to pad fitted graphs based on cover-aware top.
packages/​renderers/​kit/​src/​react/​zoom.ts Adjusts opening scroll placement and reacts to cover easing transitions.
packages/​renderers/​kit/​src/​react/​shell/​kit-renderer.tsx Provides StageCover context and sets data-cover-easing.
packages/​renderers/​kit/​src/​react/​shell/​frame.ts Adds StageCover context + useStageCover() hook.
packages/​renderers/​kit/​src/​react/​shell/​cover.ts Implements useStageCoverOf() to parse token + indicate easing window.
packages/​renderers/​kit/​src/​react/​graph-canvas/​laid-out-graph.tsx Applies computed cover-aware top padding via --pk-fit-top.
packages/​renderers/​kit/​src/​react/​graph-canvas/​framing.ts Integrates useCoveredPadding for cover-aware fit padding.
packages/​renderers/​kit/​src/​react/​covered-padding.ts New hook computing cover-aware fit padding from stage-cover.
packages/​renderers/​kit/​src/​react.ts Re-exports useStageCover and useCoveredPadding.
packages/​renderers/​kit/​src/​fit.ts Adds CoverRect, parseStageCover, coveredTop, and coverGap.
packages/​renderers/​dependency-injection/​src/​styles.css Uses --pk-fit-top for cover-aware top padding.
packages/​renderers/​dependency-injection/​src/​renderer.tsx Uses useCoveredPadding and marks SVG to participate in easing.
packages/​renderers/​dependency-injection/​src/​diff.tsx Same as renderer: cover-aware padding + easing class.
packages/​renderers/​dependency-injection/​src/​card.tsx Adjusts DI padding logic when stage-cover is present.
packages/​host/​inspector/​test/​client.test.mjs Adds tests for abbreviated-hash labeling behavior.
packages/​host/​inspector/​src/​viewer/​state.ts Adds utilityAreaOn() helper (?utility=off).
packages/​host/​inspector/​src/​viewer/​mount.tsx Enables utility area in viewer via utilityAreaOn().
packages/​host/​inspector/​src/​mount.tsx Wires utilityArea option into InspectorApp.
packages/​host/​inspector/​src/​app/​revisions.ts Treats abbreviated hashes as commit names in labels.
packages/​host/​inspector/​src/​app/​props.ts Adds utilityArea?: boolean prop.
packages/​host/​inspector/​src/​app/​page.tsx Plumbs utilityArea to ProjectionView.
packages/​host/​inspector/​src/​app/​inspector-app.tsx Defaults utilityArea and passes it through in bare mode.
packages/​host/​core/​src/​ui/​view/​utility.tsx New utility-area playback bar + layout helper hook.
packages/​host/​core/​src/​ui/​view/​props.ts Adds ProjectionViewProps.utilityArea.
packages/​host/​core/​src/​ui/​view/​host-views.tsx New wrapper to render table/text with floating utility content.
packages/​host/​core/​src/​ui/​view.tsx Integrates utility area into default host UI (stage/table/text).
packages/​host/​core/​src/​stage/​utility.tsx New UtilityArea component and layout constants.
packages/​host/​core/​src/​stage/​labels.tsx Marks chips as cover elements and supports max width for swipe.
packages/​host/​core/​src/​stage/​cover.ts New measurement logic to compute stage-cover/stage-inset-top per frame.
packages/​host/​core/​src/​stage/​body.tsx Measures cover, injects theme tokens into pane environments, renders utility area.
packages/​host/​core/​src/​stage.tsx Adds ProjectionStageProps.utility.
packages/​host/​core/​browser/​pane-labels.spec.ts E2E asserts stage-cover values and utility bar behavior.
docs/​reference/​theme-tokens.md Documents new stage-cover token semantics.
docs/​reference/​renderer-sdk.md Updates optionalThemeTokenNames docs.
docs/​reference/​renderer-messages.md Updates optionalThemeTokenNames docs.
docs/​reference/​renderer-kit.md Documents new fit/cover exports and hooks.
docs/​guides/​renderer-kit.md Updates guidance to reference cover-aware padding.
docs/​guides/​host-core.md Documents utility area and stage-cover behavior.
docs/​design/​utility-area.md New design note explaining the utility area + cover tokens.

Review effort: Lite

Comment thread packages/host/core/src/stage/body.tsx Resolved
Base automatically changed from toolbar-centred-cluster to main November 20, 2026 03:05
@agorischek
agorischek force-pushed the utility-area branch 3 times, most recently from 6e1f7fb to 58c2646 Compare November 20, 2026 15:20
@agorischek agorischek changed the title Prototype the stage's utility area: labels and playback float over the stage The stage's utility area: revision chips and playback float over the stage Nov 20, 2026
@agorischek
agorischek marked this pull request as ready for review November 20, 2026 17:55
@agorischek
agorischek requested a balanced review from Copilot November 20, 2026 17:55

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved issues break Space-key playback in table and text views, allow the floating bar to obscure first-row content, and leave chip subject text below the required contrast threshold.

3 open issues
2 resolved since last review

Review effort: Balanced

Comment thread packages/host/core/src/ui/view.tsx Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved issues leave opening content obscured by the corner chip, break Space-key playback in table/text views, and render commit subjects below WCAG AA contrast requirements.

4 open issues

Review effort: Balanced

Comment thread packages/host/core/src/ui/view.tsx Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The zoom calculation incorrectly offsets centred focus areas and omits drawing padding, causing content to clip below the unobscured viewport.

1 open issue
4 resolved since last review

Review effort: Balanced

agorischek and others added 2 commits November 20, 2026 11:28
…stage

The third bar above the stage (each pane's label band in side by side and swipe,
the playback row in animated) becomes room floating over the stage's top edge,
12px from its top and sides and as wide as it needs, so the viewer never stacks
three full-width bars (docs/design/utility-area.md).

- Side by side and swipe label their panes with chips on the stage: the before
  chip at its pane's top left, the after chip at its pane's top right, in the
  playback bar's fill, edge, corners and muted text, on whole pixels.
- Animated, and the table and text views, float playback in a centred bar at
  most 560px wide, sticky below a host's stuck toolbar in a page-flow stage.
- The stage tells each frame what it covers: the new optional `stage-cover`
  layout token (the rectangles, in the frame's coordinates) beside
  `stage-inset-top`. Content that scrolls pads by the band; a fitted canvas
  moves its top only where its fit would reach a rectangle (the kit's
  `useCoveredPadding`, used by the graph canvas and the dependency injection
  renderer). A new cover is fitted to at once, never eased.
- API: `ProjectionStage`'s `utility`, the default UI's and Inspector's
  `utilityArea`; the viewer page turns it on.
- A revision named by an abbreviated hash no longer reads the commit twice.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- A chip's commit subject takes the name's muted colour, in the text face: the
  subtler colour fell below 4.5:1 on the chip's fill.
- Space toggles playback from the floating bar over the table and text views
  too: the handler is on the panel that holds both.
- A fitted drawing that opens scrolled (at the text floor, or zoomed) draws with
  a top of at least `stage-inset-top` under a cover (`useScrolledPadding`), so
  its first row opens clear of the bar or chips even where the opening offset
  clamps to zero. The graph canvas and the dependency injection renderer use it.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A centred focus opening is placed in the same scrolled padding as a reading
start, so the padding never changes when the person zooms or pans away and the
view doesn't jump. StageZoom no longer needs to say whether it's opening.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Zooming can unnecessarily increase top padding for drawings that still fit vertically, causing a visible jump because no vertical scroll range exists to compensate.

1 open issue
1 resolved since last review

Review effort: Balanced

agorischek and others added 2 commits November 20, 2026 17:12
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A drawing zoomed in that still fits the stage's height doesn't scroll down, so
it keeps its padding and doesn't move as it zooms.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The tall guard can leave vertically fitting drawings obscured by the playback bar with no vertical scroll range to reveal the covered content.

1 open issue
1 resolved since last review

Review effort: Balanced

scrolledPadding pads a drawing drawn larger than its fit just enough to clear
the stage's bands where, centred, it would reach them, and by the bands once it
scrolls, so a wide drawing opened at the text floor never sits under the bar.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because reinitialization can drop cover insets after re-extraction or focus changes, allowing content to render beneath visible floating controls.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Switching between Side by side and Swipe leaves useWholePixels observing a detached element, allowing the replacement chip to render on fractional pixels.

1 open issue

Review effort: Balanced

Comment thread packages/host/core/src/stage/body.tsx Resolved
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Renderer reinitialization can discard cover geometry, and focus framing can place content behind playback controls instead of fitting it within the unobscured area.

2 open issues
1 resolved since last review

Review effort: Balanced

Comment thread packages/host/core/src/stage/body.tsx Resolved
…r of the bands

The frame keeps the environment the host last set across a new init, so a
refresh or new focus keeps the covers. A focus opening fits and centres its
area in the room the stage's bands leave.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human review is needed to assess an environment-propagation issue that can cause content to render beneath floating controls after refresh or focus changes on an already-ready frame.

No open issues 🎉

2 resolved since last review

Review effort: Balanced

# Conflicts:
#	packages/renderers/dependency-injection/src/card.tsx
@agorischek
agorischek merged commit 9452246 into main Nov 21, 2026
47 checks passed
@agorischek
agorischek deleted the utility-area branch November 21, 2026 05:24
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.

2 participants