Storyboard

The Storyboard is a canvas with live thumbnails of every screen of your app and the navigations between them. You see the whole app at once, open any screen with a click and, with Copy for AI, tell the assistant exactly which screen to change.

It only shows in debug. It does not exist in production.

ImplementationCopy Anchor Link

1. Run the app in debug on the web (kasy run --web). The Storyboard opens from the device preview bar, which only exists on the web.
2. Open the Storyboard from the button on the device preview bar.
3. Use search to find a screen by name or route. Two clicks open the screen in the app.
4. Select a screen and tap Copy for AI. Paste it into the assistant chat.

The copied text carries the screen, route, widget and section, for example:

Storyboard context (Kasy)
Screen: Phone sign in
Route: /signinWithPhone
Widget: PhoneAuthPage
Section: Entry & sign in

5. After the AI edits the code, tap Reload. It runs the same hot reload as r and remounts the screens, so you see the change live.

Ask the AI to organize the mapCopy Anchor Link

All presentation lives in lib/core/storyboard/storyboard_registry.dart. Ask, for example:

• "Rename the /orders screen to My orders in the Storyboard."
• "Put the checkout screens in one section."
• "Add an arrow from Cart to Payment labeled Checkout."

Arrow rule: an arrow exists only for a button or link that really exists in the screen's code. An invented arrow misleads whoever reads the map.

InformationCopy Anchor Link

How screens are groupedCopy Anchor Link

• The app tabs become the App tabs section, and /admin screens go to the Admin console.
• Routes sharing the first segment become a section (/orders and /orders/detail form "Orders").
• A new, isolated screen lands in Your screens.
• A nested route draws the sub-screen arrow by itself.

Each screen shows onceCopy Anchor Link

When two routes open the same screen (for example, Feedback from Settings and from the admin console), the Storyboard shows a single card. The paths stay on the map: arrows that led to the repeated route point to that card.

• It is automatic when both routes open the same page class (FeedbackPage, for example).
• If the same screen is wrapped differently, the AI marks the route in the registry with aliasOf.
• If a route opens the same page with very different content and you want to see both, the AI sets showSeparately.
• A route that shows different screens depending on its parameter (like the paywalls) becomes one card per variant with variants.

ArrowsCopy Anchor Link

• Navigation: curated in storyboard_registry.dart.
• Sub-screen: automatic, from nested routes.
• Learned from use: while you use the app, the Storyboard notes "screen A led to screen B" and draws a dashed arrow. Clear erases what was learned.

Screens with parameters and sample dataCopy Anchor Link

A route like /drive/ride/:rideId needs a value to render. The registry takes a sampleLocation (for example /drive/ride/preview) and the app uses the value preview (kStoryboardPreviewParam) to show sample data in debug only. Sign-in screens render as Guest so they are not redirected when you are already signed in.

Performance and zoomCopy Anchor Link

On open, the map focuses the Sign-in and entry section (not the whole project). When zoomed out, cards stay light (title and route); live thumbnails and snapshots load only when you zoom in. Use Entry in the toolbar or Fit all screens in the corner to change the view. Seen in use arrows are hidden by default (turn them on in the toolbar if you want them).

Each thumbnail is the real screenCopy Anchor Link

Each card runs its own route in an isolated app, with the same theme and language. The selected screen and the ones in view when zoomed in run live; the rest become a photo of the screen itself, so the map stays light. Zoom in or select a screen to make it live again.

Last updated on 11/03/2026