Skip to content

feat: canvas, Inspect (Dev tab), screen sizes, guided tours and versions - #8

Merged
hugobessa merged 44 commits into
mainfrom
feature/canvas-and-versions
Nov 17, 2026
Merged

hugobessa merged 44 commits into
mainfrom
feature/canvas-and-versions

Conversation

@otavioribeiro-commits

@otavioribeiro-commits otavioribeiro-commits commented Nov 17, 2026 •

Copy link
Copy Markdown

Why

  • building-blocks' billing prototype uses useVersion() and <Since> to show its V1, V2, V3 and Later scopes. A release with this PR lets a fresh checkout of building-blocks render.
  • The canvas, the Dev tab (Inspect) and the guided tour player are already used day to day against building-blocks and the PDS projects (the SleepMD tours come from the player).

What

  • Inspect / Dev tab: turning Inspect on (i) opens the Dev tab. Picking an element shows its component, path, anchor id, Storybook page and source line with Open in editor; styles read back to tokens; size; role, accessible name, contrast and keyboard reach; a JSX snippet under the dev server.
    • Measure (m, or Alt + hover): distances from the picked element to the one under the pointer.
    • Download PNG beside Inspect: saves the screen on the stage, or the picked frame on the canvas, at twice its size. The image leaves out the inspect outline, its label and comment pins.
  • Canvas (v): every screen state as a frame on one canvas you can pan and zoom.
    • Sections per screen, laid out in the flow's columns. Drag or Space-drag to pan; Ctrl/Cmd + scroll, pinch, or +/- to zoom; Shift+1 fits all, Shift+2 zooms to the picked frame.
    • The flow map becomes the canvas's arrow layer (a); f opens the canvas with arrows on. The header's Flow button becomes Canvas.
    • Sections can be dragged and Reset layout restores the columns. The layout, two-viewport mode and Ready for dev marks are saved to canvas.json through the dev server.
    • Live frames (L), full-page frames, comment pins on frames, PNG export of the picked frame.
    • Draws only the frames in view, so a 60-state fixture stays smooth (example/prototypes/canvas-sixty).
  • Screen sizes and fullscreen: Mobile / Tablet / Desktop, device presets, a typed or dragged size, rotate and zoom, on the stage and on the canvas; Present (p) shows only the screen, Esc exits.
  • Guided tours (the player): prototype-lab player builds each prototype's tours/*.json into one HTML file that opens offline with a double-click. #/check checks every step and click. Ships the build-guided-tour skill beside build-prototype.
    • Tours button: once the player file exists, the viewer's header shows Tours, which opens it in a new tab. dev serves the file beside the viewer and build copies it into the static copy. A project without a player shows no button. The folder is player.outDir (default prototype-lab-player).
  • Versions: version-<id> lines in prototype.md, a picker after the prototype picker, ?v= in the route.
    • Screen states and comments take since / until; screens use <Since> and useVersion().
    • The screen list, counters, canvas, arrows and comments follow the pick. All shows chips. A link outside the version shows a toast; a deep link shows a placeholder. Unknown ids are listed in Problems.
    • Prototypes without versions are unchanged.
  • The header fits a 13-inch laptop (1440px) on one row: button labels show from 1920px, the "Prototype Lab" name from 1560px. Side panels and the prototype picker animate (instant with reduced motion).
  • A viewer linked to a checkout no longer goes blank while the package rebuilds.
  • README and an Unreleased CHANGELOG entry for all of the above.

Reviewer notes

  • The canvas, Dev tab and pickers use feat: device toolbar, resizable frame and present mode #5's toolbar API (DeviceSettings, the frame and fill present modes, the viewport switcher, viewportSwitcher: false).
  • Breaking: the FlowMap export is removed; CanvasView replaces it. Worth a minor bump.
  • SleepMD / PDS projects: to show the Tours button, set player: { outDir: 'public/tours' } in prototype-lab.config.ts and run prototype-lab player without --out-dir.
  • New dependencies: dom-accessibility-api (MIT) and html-to-image (MIT, loaded only on PNG export).
  • Large PR: reviewing commit by commit follows the order the features were built.

Testing

  • pnpm check, typecheck, test, build, publint, build:example and the smoke test pass locally on Node 24.
  • Tests cover the Tours link only with a built player, the dev server serving the player once written, player.fileName validation, Download PNG in the Dev tab and its error, and the PNG export filter, beside the canvas, Dev tab and versions suites.
  • Checked by hand on this repo's example prototypes with pnpm dev: Inspect, Measure, Download PNG (image saved without overlays), canvas fit and zoom to frame, Mobile / Tablet / Desktop, Present and Esc, the Tours button and a tour playing. build:example writes tours.html beside index.html.

Recordings

Recorded on this repo's example prototypes with pnpm dev, at 1440 × 717.

Inspect, Measure and Download PNG: i turns Inspect on and opens the Dev tab; picking Book a visit shows its component, source, snippet, accessibility and tokens; m and hover measure the distance to View medication; Download PNG saves the screen.

pr8-inspect-measure-download

Canvas: f opens the canvas with arrows, Shift+1 fits the flow, picking Review and zooming to it.

pr8-canvas

Screen sizes and fullscreen: Tablet, Desktop, back to Mobile, then Present shows only the screen and Esc returns.

pr8-screen-sizes-present

Tours: the header's Tours button opens the player; a tour plays step by step with the panel of steps beside the screen.

pr8-tours

Versions: pick V1 and the Invoice screen drops its V2 state; back on All, the V2 state shows a chip and the V2 button returns.

pr8-versions

🤖 Generated with Claude Code

Otávio Ribeiro and others added 30 commits October 23, 2026 11:29
…vice frame helpers

measureAnchor scales a box measured on a frame drawn by a CSS scale() back to
the frame's own pixels, so pins and outlines line up at any zoom.

Adds the device presets, breakpoint snapping, drag and fit math, the
remembered device settings, and the ?present address flag the device toolbar
and presenting mode build on.
PrototypeFrame takes a size from the device toolbar and stops narrowing to the
stage when it has one. ResizableFrame draws it at a zoom with handles on the
right edge, bottom edge and corner, snaps widths to the breakpoints, and goes
back to the device size on a double click.
Each handle is a focusable separator that reports the side it moves; the
arrow keys change it by 10 px, or 50 px with Shift.
DeviceToolbar offers the screen default, a free size, and phone, tablet and
desktop presets, with width and height fields, rotate, and zoom. The header
shows it in place of the viewport switch when given one, adds a Present
button, and on a narrow window drops button labels, then the title and the
size fields, and scrolls sideways before it wraps.
…le page

PresentingStage shows only the screen, filling the window, with a way out
that hides after a moment and returns on any touch, or Esc. useVisibleBox
follows the visual viewport, so browser bars and the on-screen keyboard on a
tablet never scroll the page. useElementSize and useWindowViewport measure
the stage and the window.
The stage draws the screen in a resizable frame at the size the device
toolbar sets, fit to the stage or at a set zoom, and remembers both in this
browser. The flow map follows the device's viewport. P or the Present button,
or ?present in the address, gives the screen the whole window.

The viewer now opens with the doc panel shut and comments hidden, so the
screen has the room; ] and c bring them back.
A project's stylesheet loads after the viewer's and shares its utilities
layer, so its .flex or .gap-2 won over the viewer's narrow-window rules. The
responsive header classes are marked important. The device toolbar's selects
and size fields are h-8, the height of the header's buttons.
With the package linked from a checkout and rebuilt in watch mode, Vite swapped
dist/index.js in place, and the screens kept the old copy's React context, so
useScreenNavigation threw. The dev server now reloads the page for a change to
a built script, and still updates stylesheets in place.
…do it

dev-with-bb.sh builds the package, keeps it rebuilding, and starts
building-blocks' prototype viewer on it. back-to-npm.sh puts building-blocks
back on vinta-prototype-lab 0.1.2 from npm with its local patch and
reinstalls.
Every screen state is a frame on one canvas, in a section per screen laid out
in the flow's columns. Pan by drag, Space and drag, scroll or the arrow keys;
zoom from 5% to 200% with Ctrl or Cmd and scroll, pinch, + and -; Shift+1
fits everything and Shift+2 the picked frame. Tab and the arrow keys move
between frames, Enter or a double click opens one on the stage. Picking a
frame opens that screen state, so the URL and the panels follow the canvas.
Comment pins sit on the frames and open their comment in the panel.

The flow map becomes the arrow layer (a); f opens the canvas with it on.
Frames draw only while in view, two per animation frame, and wait while a
pan moves; below 20% they are title cards. With the generated 60-state
fixture the canvas is usable in about half a second and pans at 60 fps.

FlowMap is no longer exported; CanvasView takes its place.
Drag a section by its name, or focus the name and move it with the arrow
keys (Shift for a bigger step); Reset layout puts every section back in the
flow's columns. Frames sit inside their section, so a drag moves one element.

The arrangement is written to the prototype's canvas.json through a new dev
server endpoint, /__canvas, beside /__annotations and with the same checks;
the viewer's own writes do not reload the page, a hand edit does. A section
for a screen that is gone is dropped with a line in Problems, and a new
screen is placed to the right of the arranged ones. A built copy draws the
saved arrangement and offers no way to change it.
L, or a double click with Live on, makes one frame click through inside
itself on a history of its own, without moving the screen the viewer has
open. Its title offers Back to its own state; Esc, its X, or a press
elsewhere on the canvas makes it inert again. It scrolls its own screen with
the wheel, and an Esc a screen's menu used does not stop it. Portals render
in the page, over the canvas (D-C3: same document).

The canvas can draw every state in two viewports side by side; the choice is
saved in canvas.json, or kept on the page in a built copy.

Also: inert frames run no animations or transitions, which kept the browser
recompositing every frame (60 fps again with 28 screens drawn); a frame that
takes focus from the keyboard is brought into view by the camera, and the
canvas element itself never keeps a scroll offset; a frame picked on the
canvas is no longer panned under the pointer. The fixture's long lists now
scroll.
The Dev tab of the right panel says how the picked element is built, on the
stage and in the picked frame of the canvas, where Inspect now works: the
component's name, path, id, Storybook page and source line, with Open in
editor through Vite's own /__open-in-editor; every colour, spacing,
typography, radius and shadow value read back to the utility that set it and
the token behind it (Tailwind's --color-* name, or the bare name of a theme
declared inline), flagging a value no token produces and never guessing one;
and the size in frame pixels.

Measure: Alt and hover another element draws the distances to it in frame
pixels; with nothing picked, Alt shows an element's padding and margin. M
turns measuring on, and focusing a row of the component tree measures to it,
so it works from the keyboard. The tab lists the distances and the box model.

Fixed: the hover outline on the stage was cleared by its own drawing, which
the component tree read as a change to the screen.
…port

Dev tab: the role and accessible name (dom-accessibility-api), the text
contrast against the composited background with pass or fail for AA (4.5,
or 3 for large text), and whether the keyboard reaches the element or why
not. Colours are read in rgb, color(srgb), oklch and oklab; any other form
reads as unknown rather than a guess. Under the dev server it also shows the
element's JSX as written, children collapsed, read through a new
/__source-snippet endpoint with the same checks as the others, with a copy
button. Open in editor now sends the 1-based column editors expect.

Canvas: Ready for dev marks the picked screen state, saved in canvas.json
next to the layout, with a badge on the frame; a mark for a state that is
gone is dropped with a line in Problems. PNG saves the picked frame's screen
at twice its size, through html-to-image, loaded only on use.

New dependencies: dom-accessibility-api and html-to-image, both MIT.
Inspect was a crosshair icon in the header, without a label on narrower
windows, and the I key. The Dev tab, which needs it, and the canvas toolbar
now have a button that says Inspect and shows when it is on.

The canvas toolbar stays on one row: on a narrow stage it scrolls sideways
and the hint gives way, instead of growing a tall column.
The header's crosshair, next to the Canvas button, already turns Inspect on
and off on the canvas too, and the Dev tab keeps its own button.
…device height

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…y when it is out of view

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ebuild no longer leaves it blank

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A branch picker beside the prototype picker lists the local branches of
the repository the project sits in and runs `git switch` there, then
reloads. Opt in with `prototypeLab({ branchSwitch: { localOnlyFiles } })`;
the entry only turns it on while serving, so a built copy never has it.

- Blocks on uncommitted changes outside the local-only files and on a
  merge, rebase, cherry-pick, revert, bisect or running git command.
  Never stashes, discards or resets.
- Asks for a second click when a watched file changed in the last five
  minutes, or a live `.prototype-lab/sessions/<id>.json` marker exists.
  Stale markers (pid gone, untouched for 12 hours) are ignored.
- Local-only files are copied aside, restored to HEAD, and written back
  after the switch, merged onto the branch's version where it changed.
- Offers the install when the lockfile differs; the note survives the
  reload Vite triggers.
- The endpoints take requests only from a loopback Host on the server's
  port, and writes need JSON and a matching Origin. The branch must be
  one `git branch --list` lists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Prototypes declare versions with version-<id> front matter keys. Screen
states and notes take since and until; unknown ids become load problems
and the item reads as in every version. The hash route reads and writes
?v=. useVersion and <Since> read the picked version from the runtime and
act as All outside it.
The header shows a version picker after the prototype picker when the
prototype declares versions. The pick lives in ?v= and stays as the
screens change. The screen list, its counters, the canvas, the flow
arrows and the notes show only the picked version; All shows every state
and note, with a chip on those not in every version. A link to a state
outside the version shows a toast, and a deep link to one opens a
placeholder with buttons to switch. The example invoice list gets two
versions, a V2 state and a <Since> part, with an integration test.
Otávio Ribeiro and others added 12 commits November 17, 2026 11:13
Brings in the reviewed device toolbar (0.3.2): DeviceSettings, the frame
and fill present modes, the viewport switcher kept beside the toolbar,
and the Vinta wordmark. The canvas, Dev tab, version picker and branch
picker now use that API. The branch's own copies of the toolbar files
give way to main's.
CI checks out one commit with no local branch, so the dev server test
checks the branch endpoint's answer rather than a branch count; the
branch-switch tests list real branches in a temporary repository. The
PNG test waits for the picked frame's screen, which the canvas draws a
couple of frames at a time.
…ner passes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The viewer no longer switches the host project's branch. The unreleased
`branchSwitch` option, its dev-server endpoints and the header picker are
gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`prototype-lab player` builds each prototype's tours/*.json into one HTML
file that opens offline. #/check checks every step and click. Ships the
build-guided-tour skill beside build-prototype.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…r player

The plugin looks for the player at player.outDir/player.fileName. Under dev it
serves the file beside the viewer and reloads when it appears or goes; build
copies it into the static copy. Without the file the header shows no button.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Saves the screen on the stage, or the picked frame on the canvas, with the
same export the canvas toolbar uses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The device toolbar from main and the Tours button made the row overflow at
1440px. Button labels now show from 1920px, and the Prototype Lab name from
1560px; the Vinta mark stays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nt pins

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@otavioribeiro-commits otavioribeiro-commits changed the title feat: canvas, Dev tab, versions and branch picker feat: canvas, Inspect (Dev tab), screen sizes, guided tours and versions Nov 17, 2026
Otávio Ribeiro and others added 2 commits November 17, 2026 13:38
The player test resolves the package from source, so it passes without a
build, and the header's classes are in Biome's order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tours

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pamella

pamella commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Hey @hugobessa! @otavioribeiro-commits put together PR #8, which brings in everything he's added to the prototype lab: canvas, Inspect (Dev tab), screen sizes, guided tours and versions. I mainly reviewed the folder structure and the .md files.

We know it's too big. Of the +22k lines:

  • ~10.2k are a generated example with 60 screens (example/prototypes/canvas-sixty/), so you can skip them.
  • ~3.6k are tests.
  • ~0.5k are docs, skills and other examples.
  • ~7.7k are the actual implementation in src/, and that's still a lot for a single review.

Otavio put it all in one PR because he had everything working together in his local environment. We don't know how you usually like to review this repo, though. If you'd like it split into smaller PRs (by feature, for example), just tell me and I'll do it.

@hugobessa
hugobessa merged commit 9726f51 into main Nov 17, 2026
5 checks passed
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.

3 participants