Repository navigation
The stage's utility area: revision chips and playback float over the stage - #58
Conversation
31a3b2e to
f193486
Compare
There was a problem hiding this comment.
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-covertoken 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
6e1f7fb to
58c2646
Compare
There was a problem hiding this comment.
🟡 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
169f80b to
34b506e
Compare
…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>
b5bdb97 to
e4fb894
Compare
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>
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>
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>
There was a problem hiding this comment.
🔵 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>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…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>
There was a problem hiding this comment.
🔵 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

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
--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.--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.How renderers keep clear: a new optional layout token,
stage-coverx y width height, …). Beside them it sendsstage-inset-top, the band they take. The host decides the cover, never the content, so there's no feedback loop.ContentView,pk-stage) pads its top by the band, as it already did under chips, and scrolls under it.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.API:
ProjectionStage'sutilityprop, the default UI'sutilityArea, and the Inspector'sutilityArea. The viewer page always turns it on.Also
5c95b54e0d1b · 5c95b54e, the same commit twice. A 7–39 digit hex prefix of the commit now names the commit once.Tests
parseStageCoverandcoveredTop, covering a flat graph, a tall graph against the chip and the bar, and a stage offset in its frame.pane-labels.spec.ts: each frame'sstage-covermatches 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.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.Tables (API renderer, Side by side) and playback over tables (database renderer, Animated):
Open questions (also in the note): whether
stage-coverbelongs in the renderer environment rather than in theme tokens, and whether the bar should carry the revisions' names beside the slider.