Routing

The URL always represents the view the user is looking at, so every screen can be bookmarked, shared, reloaded, and walked with Back/Forward.

Where it lives

Routing is a UI concern: packages/ui/src/ui/router.ts defines the serializable RouteRef union, the routeToHash / parseHash pair, and the useHashRoute hook. Workspace owns the mapping from a RouteRef to a rendered screen.

The hook itself is useHashRouter in routerCore.ts, over any app's routes and its pair of functions. The Studio has routes of its own and keeps them with the same core; this page is about Solid Memo's.

The Studio shares Solid Memo's page. Its routes are the hashes under #/studio (STUDIO_PATH; isStudioHash tells them apart), and none of Solid Memo's is one of them. The page (apps/web/src/App.tsx) follows the hash and shows Solid Memo's Workspace or the Studio's, so a link between the two apps is a plain hash link. Solid Memo links to the Studio with studioHref: the instance's Home there, #/studio?instance=…. The instance bar, each deck's actions menu and the deck page have this "Open in Studio" link. Solid Memo cannot import the Studio's router, so studioHref spells that route itself, and a Studio test checks that the two agree.

Within the Studio, its sidebar's sections, decks and drafts, the tabs of a deck or a draft, and the palette's entries that go somewhere (studio.md), are links to its routes: following one pushes a history entry, as any link does, and none adds a route or a parameter of its own. The chrome around a screen (which section, deck or draft the sidebar marks, which tabs there are and which is current, whether the aside shows a course's outline, a deck, a library copy's upgrade or a card) is worked out from the route alone, and hiding the sidebar, the aside or the dock, or a table's columns, changes no URL (studio.md). F8 goes to a problem's field as a link does.

A card's route, #/studio/card, also carries the card workbench's query, so the deck's cards stay listed beside the card: the workbench's own parameters (q, lang, state, has, sort, order, page, size), but in for where to look, as the card's field is the field it opens at. They are optional: a link to a card without them lists the deck's cards as the workbench does by default. Opening a card from the list pushes a history entry; going from card to card beside it (j and k, Previous and Next) replaces it, as does putting the list at the page of a card opened from elsewhere. While the card's edits are not saved, a hashchange (Back, Forward, a hash typed in) is undone before the router hears of it, by going as many entries the other way, and asked about first (studio.md). To tell how far, the router numbers the entries it sees (position in each entry's state, read by historyPosition and shownPosition in routerCore.ts): one more for each entry after another, as it pushes one or hears of one the browser made; a replace keeps the number. No entry is pushed to undo a move, so the history after it is kept.

Home's route, #/studio, carries the view its tabs show (show: due, courses, copies or attention; every deck without it) and the deck beside its table (deck, the deck at the table's cursor). A draft's cards, #/studio/draft-cards, carry how they are sorted (sort and order=desc). Each is optional, and each change of them replaces the history entry: it is the same screen, looked at another way (studio.md).

Hash routing, not pathname routing

The route is kept in location.hash:

• Deep links work on any static host — no server rewrite rules.
• The Solid OIDC redirect uses the query string (?code=&state=); the hash stays clear of it.

Route scheme

Instances and decks are Solid resources, so their identifiers are full URLs, carried URL-encoded in hash query parameters.

Resolution and fallbacks

The hash carries identifiers only; Workspace resolves them to domain objects before rendering:

The diagram's source

flowchart LR
    accTitle: From the hash to a screen
    accDescr: The location hash is parsed into a route of URLs, whose instance and deck are queried before the screen renders.
    hash["location.hash"] -->|parseHash| ref["RouteRef (URLs)"]
    ref -->|instances query| instance["Instance"]
    ref -->|decks query| deck["Deck"]
    instance --> screen["screen component"]
    deck --> screen

• The deck lookup shares the ["decks", instanceUrl] query cache with the home screen, so in-app navigation resolves without a refetch. The deck list itself reads the decks as arranged into groups, under ["decks", instanceUrl, "tree"], so whatever refreshes the decks refreshes their arrangement too; on the home screen, the decks in that arrangement fill ["decks", instanceUrl], so the catalog is read once. A library deck is resolved the same way from the ["library"] cache the library screen reads.
• The header logotype links to #/ — deliberately not a route — so it lands on the default route: the deck list, or a picker when the instance is ambiguous.
• Invalid or unknown routes never strand the user: an unparsable hash falls back to the default route (home / instance picker / storage picker, by instance count), an unknown instance falls back to the instance picker, an unknown deck to that instance's deck list, an unknown library deck to the library, an unknown library card to its deck's cards. All fallbacks use history.replaceState, so they are not Back stops; in-app navigation uses pushState, so Back walks the screens.

A link to a library deck

Every other route names an instance, which only its owner can open: a guest's is an address under guest.solid-memo.invalid that exists in their browser alone. So a library deck's page copies a link that names none, #/try?deck=… (tryHref), for anyone to open:

The diagram's source

flowchart TD
    accTitle: Following a link to a library deck
    accDescr: Without a session, the link starts a guest's study first; then, once the library is read, it goes on to the deck's page in the learner's instance, or the one they choose, or to the library when the deck is not in it or the library cannot be read.
    link["#/try?deck=…"] --> session{"a session?"}
    session -->|no| guest["a guest's study starts, or the one in this browser goes on"]
    session -->|yes| count
    guest --> count{"instances"}
    count -->|none| storages["#/storages: make one"]
    count -->|one| known
    count -->|several| picker["the instance picker: which to open it in"] --> known
    known{"in the library?"} -->|yes| deck["#/library-deck in that instance"]
    known -->|no| library["#/library in that instance, saying so"]
    known -->|the library unread| unread["#/library in that instance, with its error"]

• Without a session, AppShell starts a guest's study (guest-mode.md) instead of showing the landing page, when the page loads at the link or the link is followed on the landing page. With one, a guest's restored or the user's, it goes on with it.
• Then Workspace reads the instances and the library. With one instance, it opens the deck's page there; with several, it shows the instance picker, which asks which to open the deck in, and opens it in the one chosen. Each replaces the link, so Back does not return to it. With none, it goes to the storage picker, to make one, and the deck is not opened.
• A deck the library does not have opens the library instead, which says so above it. That is kept in memory, not in the URL, and dropped as the learner leaves the library. A library that cannot be read opens there too, where its error says why, and nothing is said of the deck, which may well be in it.
• A course opens at its page in the library, as any deck, where it is started, or continued when the instance has it already.

Breadcrumbs

breadcrumbsFor(route, names) in packages/ui/src/ui/Breadcrumbs.tsx derives a trail from the current route alone — Decks › deck › Browser › card — and Workspace renders it above every screen. Every crumb — the current page included, marked aria-current="page" — is a plain <a href="#/…"> link built with routeToHash, so following one is an ordinary hash navigation: Back/Forward, new-tab and keyboard use all work without extra code. The trail is the way back up: screens have no "Back to …" buttons, save where going back is one of the choices a screen puts to the user, as a course's final review does before it starts and a finished course does; those are plain links too. Top-level screens (deck list, instance picker) show a single crumb, so "Decks" is on hand everywhere inside an instance. The masthead's logo and "Solid Memo" title both link to #/, the root.