graview-pages
graview-pages is one of Graview's 31 authoring skills: instructions an AI coding assistant such as Claude Code or Codex reads before it changes a Graview app. What it teaches: Give a Graview app the routed face it wants — from the derived pages, to one page in the app's own words, to the door of a product design that replaces every surface (graview-pages-design).
Installed into a project by graview skills install ., and read by whichever assistant is working beside you.
The skill
The pages face
A Graview app has two faces over one store. The scene is the picture. The pages face is the same declaration routed as an ordinary web application: a home, a list per kind, a record per node, forms for every act, and a problems page — derived, then replaceable one surface at a time, up to a product design of its own. The ladder ends at the framework's own example: apps/seedbed, chapters nine and thirteen.
What comes for free
// main.tsx — one branch: the path decides the face
if (location.pathname.startsWith("/pages")) {
root.render(<PagesApp basename="/pages" context={{ store, brand, principal, sceneHref: "/" }} />);
}PagesApp renders with no registry at all:
/— a GALLERY. The standing as the headline ("2 gardeners, 3 plots and 1 planting." or "Nothing here yet."), then every picture as a large live card, the kinds as a row of counts, a line to the map, and Recently. A kind with no titled lens gets a contact sheet of its members, so a new app lands on a gallery. An empty picture names the act that fills it./<plural>— a list per kind, marking trouble, its creating acts beneath./<plural>/<id>— a record: its facts, changed where they stand, its relations in the declaration's words, what can be done, what happened./problems— every broken rule, with repairs.
The app bar, one row over any shell (barAbove): the name, the switch (Scene, Pages; none with sceneUnderPages), the place you are on — whose list holds the home, the Lists, the Pictures (standing on a wide bar, else under More, as an empty kind is) — Find, standing, person. A shell with a rail of its own says surface("shell", Shell, { without: ["places"] }): the bar keeps all that and names no place. Each list, record and picture opens with a trail (nav "You are here": the section, the kind's list, the page itself current), its hrefs under the base.
Arrange it, declared: pages: { order: ["offer", "package"], hide: ["party"], first: "The offers" }. order sorts gallery, nav, city; hide keeps kinds off the home and the bar's places (listed only while you are on one), each still at its address and in Find; first (place, kind or "home") is where a new visit lands; a drawn home stays Home, on the bar and at /. primary stands on the bar. placesOf(app) (/seat) lists them. A lens only a home links to may be hidden: true (set-lens-hidden): off the bar and the page list, still at its address; set-lens-hidden on a kind (title: "party") writes hide.
A view the host keeps (a script view, by its manifest name) is view:<name> in order, first and primary: listed among the lists where ordered, opened on, stood up. The declaration cannot know the host's views, so graview check notes one not registered here ("not drawn here yet") rather than refusing it; a host hands its manifests as views to editDocument (a title then resolves: order: ["To do"] writes view:to-do), compileDocument and placesOf(app, { views }).
Home as data (FR-81): home, blocks as in graview-view-specs (views.home), replaces this body, and the app opens on it (FR-136): 40 blocks at its top (a group is one; 120 in all), and a figure may say emphasis: "large".
No home, and purpose.jobs (the face handed app): the home opens on the jobs. The first with records waiting is the title, its count, five records, its act on each; the rest smaller, the gallery after. A drawn home answers a job only by listing its kind (design-job-unanswered). composeDesign(document) (@graview/core/compose) proposes jobs, a home, rows and glances where missing, the critic's edits and an accent.
Hand it views (the scene's registry, plus settings/presence) — graview create does — and the face puts the scene's provider under its routes:
/places,/places/<as>— every named lens as a page (fullscreen, over the kind's members, the beginning acts beneath unless the lens sayscreate: false). A kind's page lists its pictures; a pick in a lens travels to the record. A kind's own row (one × glyph) is each line of its list, and its own page view (one × full) heads its record. A script view that draws its own heading saysheading: "own"in its manifest: its place, or the page it replaces, draws nothing over it./map—kindMap(store): every declared relation in its words with its live count, also a section on the home page. A kind's list says what it relates to, arranged in the shared words (?sort=due:desc,?filter=done:false,?group=due:month,?q=tape) a lens carries in its fragment, so an arrangement is a link;?by=,?<edge>=<id>,?with=and?past=1still land. A record links back./search?q=— the Find box's matcher: hits by kind, each with why; a nav box narrows a list, else lands here. Find and the way back ("Take back “…”", ⌘Z) are on every face: a shell places<PageFind>or<PageUndo>where it wants them, else they are drawn around it (without: ["find"]goes without; at a bar's height,graview-pages-design).- The quick ask (⌘K, where
aigives a model): a bar and answer card by the page's heading, the ROUTE what "this" means.context.quickAsk: falsedraws none.
Everything a page shows is a derivation the scene uses too: recordFacts, deriveAffordances, store.permits. A page never decides what an act is or who may take it — it strikes through what the seat may not, and says why. A record's facts are one sheet, each by its type (graview-node-kind), as display.page groups them; an act that is one fact's control leaves What can be done (actsBeyondFacts, FactSheet).
Typed together. Over a served store, hand the face typing (openRemote's remote.typing; an embed passes it) and prose is edited live: each keystroke a splice, no Save, others' carets drawn. Markdown, a document's text and a string past 500 characters are; a short string is not, and stays a whole value with a Save: a name or a title is changed whole, two people merging letters into one name is a worse name, and a whole write keeps its stale-write check (markCollaborative overrides). A keystroke rides an act that writes the field and would run on the record now — its allowedWhen, its allowedOn, or its apply asked — so a record the act refuses is read only to typing too.
On a phone this face is the answer. Shell carries pagesHref.
Rung one: a page in the app's own words
createPageRegistry(schema) replaces pages per kind and surfaces per app:
import { createPageRegistry, DerivedForm, kindFacts, PageMain, pageStyles, recordFacts, SceneLink, useStoreTick } from "@graview/pages";
function PlotPage({ context }: { context: PageContext<S> }) {
const { store, principal } = context;
useStoreTick(store); // re-render on every op
const id = decodeURIComponent(useParams()["id"] ?? "");
const facts = recordFacts(store, id, { principal }); // the same derivations
return (
<PageMain context={context}>
<h1 style={pageStyles.h1}>{facts.label}</h1>
<SceneLink context={context} stop={`#focus=${id}`} />
<DerivedForm store={store} mutation={sow} prefilled={{ plotId: id }} />
</PageMain>
);
}
export const pages = createPageRegistry<S, PageComponent<S>>(schema)
.register("plot", "record", PlotPage)
.route("/survey", SurveyDesk); // about nothing in the schemaClaim a declared block, keep the rest. A block may say "key": "rewrites" (unsaid, its sort and place: list.2); <BlockSlots.Provider value={{ "change.page": { rewrites: Timeline } }}> draws yours for it and every other block as declared; a blocks lens is claimed by its address ("the-offers"). Never pick a block by its title's words.
.route(path, Component) gives a page that is NOT about a kind an address — onboarding, settings, import — matched before /:plural. Every to is basename-relative (to="/survey", never to="/pages/survey"), and so is initialPath, so a test renders the hrefs a browser will.
Rules for a page at this rung:
PageMain, not<main>— inside an embed the host owns the onemain, and a hand-written one is a duplicate landmark.useStoreTick(store)at the top of every page that reads the graph, or it goes stale after the first act.pageStylesfor the parts you did not design: one face, derived or not.- Prefill, never wire.
DerivedFormwithprefilledis how a record offers an act about itself; the form asks for the rest. - Read permission before drawing an act. `store.permits({ name, args }, principal)
, struck through withverdict.refusal.message`. A form that refuses on submit is the bug this prevents. - Link to a PICTURE, not only to a node.
spatialHref(id)opens the scene on one thing;placeHref(as)(/#view=the-grounds) on one named place. A scene not at/: setsceneHrefin the PagesApp context; both take it second. - Take the act LIST from the derivation, not from the mutations.
recordFacts(store, id, { principal }).actionsis theAffordanceSetthe scene's strip reads:affordancescan act here,argsdecided andopenquestions left;withheldare this seat's refusals, with the reason.store.allMutations()offers acts with nothing to act on. A list page asks it of a kind instead —kindFacts(store, kind, { principal }).actions, the acts that can BEGIN it.
Rung two: a product design
Replacing every surface — the shell under the bar, the home, the problems, each kind's list and record — is a product: graview-pages-design, with its own tabs lit from the section a kind's pages are in, and Find and the way back in its own bar.
On somebody else's page
graview-embed mounts the app, this face included (face: "pages", path, routing), into one element of any page.
Then find out whether it worked
pnpm build && npx graview check ./dist/domain/app.js # the declaration is still whole
pnpm test # render every page you registeredRender each registered page with PagesApp and initialPath in a test (apps/seedbed/tests/integration/chapters.test.ts). Then open it: a design that reads like an admin panel has replaced nothing.
What the check cannot see
- Whether the design's words are the domain's. The derived pages use the declaration's
descriptionandinverse; a design's own sentences must stay true as the declaration changes. - Whether a page gives every act
facts.actionsoffers room: only a person can see that.