Repository navigation
feat: canvas, Inspect (Dev tab), screen sizes, guided tours and versions - #8
Merged
Merged
Conversation
…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.
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>
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>
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 We know it's too big. Of the +22k lines:
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
approved these changes
Nov 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
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.What
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.m, or Alt + hover): distances from the picked element to the one under the pointer.v): every screen state as a frame on one canvas you can pan and zoom.+/-to zoom;Shift+1fits all,Shift+2zooms to the picked frame.a);fopens the canvas with arrows on. The header's Flow button becomes Canvas.canvas.jsonthrough the dev server.L), full-page frames, comment pins on frames, PNG export of the picked frame.example/prototypes/canvas-sixty).p) shows only the screen,Escexits.prototype-lab playerbuilds each prototype'stours/*.jsoninto one HTML file that opens offline with a double-click.#/checkchecks every step and click. Ships thebuild-guided-tourskill besidebuild-prototype.devserves the file beside the viewer andbuildcopies it into the static copy. A project without a player shows no button. The folder isplayer.outDir(defaultprototype-lab-player).version-<id>lines inprototype.md, a picker after the prototype picker,?v=in the route.since/until; screens use<Since>anduseVersion().Reviewer notes
DeviceSettings, theframeandfillpresent modes, the viewport switcher,viewportSwitcher: false).FlowMapexport is removed;CanvasViewreplaces it. Worth a minor bump.player: { outDir: 'public/tours' }inprototype-lab.config.tsand runprototype-lab playerwithout--out-dir.dom-accessibility-api(MIT) andhtml-to-image(MIT, loaded only on PNG export).Testing
pnpm check,typecheck,test,build,publint,build:exampleand the smoke test pass locally on Node 24.player.fileNamevalidation, Download PNG in the Dev tab and its error, and the PNG export filter, beside the canvas, Dev tab and versions suites.pnpm dev: Inspect, Measure, Download PNG (image saved without overlays), canvas fit and zoom to frame, Mobile / Tablet / Desktop, Present andEsc, the Tours button and a tour playing.build:examplewritestours.htmlbesideindex.html.Recordings
Recorded on this repo's example prototypes with
pnpm dev, at 1440 × 717.Inspect, Measure and Download PNG:
iturns Inspect on and opens the Dev tab; picking Book a visit shows its component, source, snippet, accessibility and tokens;mand hover measure the distance to View medication; Download PNG saves the screen.Canvas:
fopens the canvas with arrows,Shift+1fits the flow, picking Review and zooming to it.Screen sizes and fullscreen: Tablet, Desktop, back to Mobile, then Present shows only the screen and
Escreturns.Tours: the header's Tours button opens the player; a tour plays step by step with the panel of steps beside the screen.
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.
🤖 Generated with Claude Code