A framework for building applications where a typed context graph is the
interface rather than the backing store.
Node kinds declare their own fields, edges, views, mutations and invariants in
a single declaration. The framework derives spatial layout, legal actions,
agent tool schemas and accessibility labels from it.
packages/
graview/ graview THE TOOL: create, check, types, docs, describe, lens, figure, serve, skills
create-graview/ `npm create graview` — the door to `graview create`
core/ @graview/core schema, graph, invariants, op log, adapters, the checker
layout/ @graview/layout positions and planes — headless, pure
tools/ @graview/tools derived affordances, one agent tool surface
render/ @graview/render capture, composite at depth, pointer routing
react/ @graview/react the only UI binding, deliberately thin
primitives/ @graview/primitives view primitives, three lenses, the workbench
pages/ @graview/pages the routed face, derived from the same declaration
ship/ @graview/ship persistence wiring, op-log-native migrations, export, health
studio/ @graview/studio the declaration itself as a graph, edited in Graview's own interface
embed/ @graview/embed mount an app into any element: scene, Graview or pages, no Shell
guest/ @graview/guest somebody else's view in a sandboxed frame that can only ask
skills/ @graview/skills the authoring moves, each ending in a check
apps/
todo/ THE EXAMPLE — a todo list, because nobody has to be taught one
seedbed/ the example that starts EMPTY — a declared graph and no data
launcher/ the desk — a Graview app whose subject is the other apps
spike/ platform capability validation, run against a real browser
Derived affordances and the agent tool surface, generated from the same declarations; graview mcp and graview apply host it against a real store.
2026-11-15
星數
—
工具
—
可用率
—
The packages are what ships. The apps are examples.graview is the
tool a person installs; @graview/* is the framework a product imports. All
of them share one version.
Start with apps/todo. Four kinds, ten named mutations, three rules that
name their own repairs, the timeline lens bound to a task's own fields, a
declared brand and an agent seat — small enough to read in one sitting, and the
only one that asks you to learn nothing before you can learn the framework. It
found two framework bugs while it was being written, which is what an example
is for. apps/seedbed is the same framework with no data at all: what a
person meets on day one, and how a declared graph invites its first entries.
Three more apps were built here as fixtures — a household week, a tender
response and a coaching week — each to prove a specific claim: that a lens
written for one domain is reused unchanged by another, that a second app's
shell is eighty lines, that a permission model narrows the interface and an
agent seat from one declaration. They are products now, and live in their own
repositories with their histories, their harnesses and their reports; what they
proved is recorded in the framework's own tests and in the sections below. A
real product built on Graview depends on these packages the way any other
consumer does — scripts/smoke-install.mjs rehearses exactly that on every CI
run, by packing the tarballs and building a scratch app from them with no
workspace and no path mapping in sight.
Only @graview/render touches the browser or the GPU, and only through its
@graview/render/gpu entry — the main one is pure geometry, so nothing that
imports it inherits a WebGPU type dependency. Everything else runs headlessly
in CI with no browser flag.
Start a project
npm create graview@latest my-app # or: pnpm create graview my-app, or: npx graview create my-app
cd my-app
npm run dev # http://localhost:5170 — the scene; /pages is the routed face
npm run verify # typecheck, tests, build, graview check
That is a product on Graview: one declared kind with its fields, an edge, a
horizon and four named acts, one rule that names its repair, an eighty-line
shell made of framework parts, the routed face, persistence in the browser,
a headless test, a git repository and a CI workflow that checks the framework
out beside the app. src/domain/ is the whole surface; the loop from there
is declare → graview check → look at it → declare more.
To work on the framework and a product at once, a project can consume this
checkout by path instead, the way the first-party products do:
pnpm install && pnpm build # the framework, first
pnpm graview create ../my-app --link . --name "My App" --kind thing
pnpm graview:link # optional: `graview` on PATH from this checkout
pnpm graview:link is pnpm link --global for packages/graview, so
graview check, graview preview and the rest run anywhere on a machine
with the checkout and no published install (run pnpm setup once first if
pnpm has no global bin folder). graview doctor, run from a checkout with
no graview on PATH, says the same.
The chapters on the page are the app itself, not pictures of it:
@graview/embed mounts each one into its place with the scene, the Graview
and the routed pages a click apart, from the same declaration and seed the
photograph was taken from. scripts/smoke-create.mjs is what keeps this honest, on every push: it
scaffolds a project from the packed tarballs, installs it with npm and no
workspace, runs the project's own verify, reads the checker's own sentence,
breaks the schema to see tsc refuse it, installs the skills, and walks the
first hour in a real browser — the empty district, the seat planting starter
data, the derived form, a reload that remembers, the way back to empty, the
routed face and its form at phone width, axe-core in both schemes. Then the
same project under pnpm; then create-graview (what npm create graview
runs) making the identical project; then a project consuming this checkout
by path, through the CLI's own install, with a hyphenated kind, opened in
the browser too.
Run it
pnpm install
pnpm apps # the desk → http://localhost:5199
pnpm apps:all # the desk and both examples on their own ports
The desk opens any app in place, so one server is enough. It also probes each
app's own port and says which are actually serving — a live dot where one is,
and the command to start it where one is not, because a launcher that offers
dead links is worse than one that offers none.
pnpm dev # THE EXAMPLE → http://localhost:5193
pnpm dev:seedbed # the garden, planted; "Start empty" in the person's menu → http://localhost:5194
The seat answers what the graph holds without any model — where things are,
what is wrong, "what's due friday", "who's working thursday". For open
questions, give the examples a model in development:
ANTHROPIC_API_KEY=… pnpm dev # GRAVIEW_AI_MODEL=… to choose one; claude-sonnet-5-5 otherwise
The dev server holds the key and answers the page at /__graview/ai
(aiDevProxy from @graview/ship/dev); the page never sees it, and a build
carries none of it. Without a key, the seat says how to turn it on.
That is the whole setup. No flags, no Canary, no GPU: the scene renders
through the DOM path, which reproduces the plane geometry exactly because the
plane model is affine by design. What it cannot do is per-plane blur in a
shader.
It opens in whichever scheme your system asks for, remembers what you pick,
and ?theme=light / ?theme=dark forces one. The two are not inversions:
dark is a lit control surface where depth loses luminance, light is daylight
and paper where depth loses contrast and gains haze. Inverting one to get the
other gives gray-on-gray mush, because glow does not exist in daylight.
pnpm test # 1,435 tests, no GPU, no browser
pnpm typecheck
pnpm check # `graview check` against every declaration here
The capture path
?renderer=gpu opts into compositing through WebGPU. It needs Chromium 147+
launched with --enable-blink-features=CanvasDrawElement.
It renders correctly — all three planes, connectors and all — and passes every
acceptance criterion. It used to bring the renderer process down on a pointer
click; that is fixed, and pnpm capture holds the claim. The cause was not the
click. A plain hover killed it just as reliably and a keyboard selection did
not: what is fatal is the browser's own hit-test descending into a
layoutsubtree canvas child. The hosts are out of hit-testing on that path now,
which costs nothing, because updateElementGeometry does not redirect
hit-testing in this build and PointerRouter was already answering.
It is still not the default. Capture falls off a cliff past ~128 live captures
a frame, and every other claim here is measured against the DOM path.
Two earlier defects here are fixed and worth knowing about, because both
failed silently: the compositor captured the canvas size once and kept using
it after the scene became responsive, so every quad was mapped to the wrong
place; and opacity was applied both to the DOM host and again in the shader,
so a view captured mid-fade baked its own transparency into the texture and
never recovered.
The harnesses
pnpm spike # capture, composite, pointer routing, capture budget
pnpm a11y # the real accessibility tree, keyboard order, axe-core
pnpm engines # the core subset in Chromium, WebKit AND Firefox, per-engine verdicts
pnpm shrunk # the shrunk interface is the interface, scaled
pnpm seat # an agent seat does what it says, and says when there is nothing to do
pnpm chat # the chat: graph answers first, proposals apply, undo really works
pnpm navigation # traveling, and getting back
pnpm pages # the routed face at phone width
pnpm remember # edits survive a reload, and the way back to the example
pnpm menu # the menu scales: search, pins, and what you use
pnpm survey # every place a person can land, photographed
pnpm audit-ui # and what is WRONG on each: collisions, cut text, tiny targets
pnpm site # docs/site holds up at ten widths, to axe and to a keyboard, with thirteen live chapters on it
The walk that finds what is still weird between `graview create` and a
seamless app is `docs/walkthrough.md`: nine stages with acceptance criteria,
a findings log, and the rule that every finding is fixed in a package with
the criterion that would have caught it.
pnpm site:build # the chapters' bundle: apps/seedbed (and the rota's week) → docs/site/chapters.js
pnpm pack:inspect # what would actually go in each tarball
pnpm smoke # install the tarballs into a scratch project and build
pnpm smoke:create # graview create → install → its own verify → a real browser
pnpm skills # install the authoring skills for Claude Code and Codex
pnpm graview:link # put this checkout's `graview` on PATH (pnpm link --global for packages/graview)
Each writes its verdict to docs/, as criteria rather than as a pass count:
when one fails it names the claim that stopped being true.
Every harness takes --engine=chromium|webkit|firefox (or GRAVIEW_ENGINE),
and none hardcodes a browser binary: the engine choice lives in
scripts/lib/engine.mjs, and Chrome Canary is required only where the GPU
capture flag genuinely is (pnpm shrunk, the spikes).
The harnesses that drive a product — direct manipulation on a board and a
calendar, one policy narrowing three seats, an agent turn watched from
altitude, the capture path surviving a pointer, a brand reaching the pixels —
moved to the product repositories with the apps they drive, and run there
against this repository's sources.
Run npx playwright install chromium webkit firefox once — the default
engines are Playwright's bundled builds. GRAVIEW_BROWSER keeps its old
meaning: it names the Chromium-family binary for the chromium and canary
engines.
Supported browsers
The DOM path — the one that ships — is verified in Chromium, WebKit and
Firefox by pnpm engines, which runs the audit, the pages face at 390×844
and a survey pass per engine and writes per-engine verdicts to
docs/engine-matrix.json. iOS Safari is the mobile browser, so WebKit is a
launch gate rather than polish.
The floors, and what happens beneath them:
document.adoptedStyleSheets is the hard floor: Safari 16.4+,
Firefox 101+, Chromium 99+. Below it the apps do not style themselves.
@property (Chromium 85+, Safari 16.4+, Firefox 128+) drives the
altitude morph into the Graview. Where it is missing the transition
degrades to a clean cut — verified, not assumed: the matrix launches
Firefox with registered properties disabled and measures the cut.
A model on the reader's device (a host's ai.onDevice) needs WebGPU
or Chrome's Prompt API. In an engine with neither, the seat answers from
the graph and says AI isn't available in this browser — verified by the
matrix, with WebGPU switched off.
The GPU capture path (?renderer=gpu) is Chromium 147+ behind a flag,
experimental and opt-in by nature. No other engine has HTML-in-Canvas.
The apps that proved it
Three apps were built in this repository, each to prove something the todo
example could not, and each is a product in its own repository now.
A household week — people, time, capacity — was the port that proved the
framework against an existing application: its primary view is a calendar, it
proved the timeline lens, and its invariants were held to the original engine's
output violation for violation.
A tender response was built second precisely because a second scheduling
app would prove nothing. It has almost no time in it. The question it answers
is not when but did we answer what was asked, can we staff it, can we
afford it, and did we remember to say so — which is coverage, a bipartite
mapping rather than an interval. So its primary view is a matrix, and the two
failures it exists to catch are readable without a word: an empty row (a
requirement nobody answered) and an empty column (work nobody asked for). Both
are absences of a relationship, which is what prose review is worst at.
A coaching week had to justify itself hardest — a coaching-week planner is also
scheduling if you build it lazily. What earned its place is the chain it turns
on, formation → position → skill ← drill ← session: the team you intend to
put out decides which skills matter, and the skills that matter decide what
training is for. That chain spans three different pictures — a board, a matrix,
a week — and the rule that walks it end to end is not expressible in any one of
them. Its new picture was the board: things arranged where the domain
says they go, the first lens whose geometry the framework does not own. It was
also the app with a policy: three seats, one declaration, and an agent seat
that narrows with the strip.
The desk (apps/launcher) is a Graview app whose subject is the other
apps here. It reads their defineApp declarations — the same objects graview check consumes — so the index cannot drift, and the coverage lens pointed at
it answers a question about the framework rather than about a domain. It
declares itself (so graview check checks it), it has mutations (so which
app is in front of you is a showing edge, not React state — it lands in the
op log with an author, and undo closes it), and it has rules it can fail. With
only the examples to survey, two fire today, and the honest thing is to let
them: no app here uses the board or coverage lens, and the empty example draws
its own picture rather than declaring a lens. The rule accepts an argument —
record why and it stops firing — but it insists there is one.
Whether a dev server is up is not in the graph, deliberately: the graph
holds what you decided and the log holds why, and "port 5193 answered" every
four seconds is an observation about the world rather than a choice anyone
made.
Building the second app changed the framework in four places, and the third
in three more, which is what more than one app is for:
What the second app forced
Where
A workbench: inspector, standing, activity, undo, trail, Escape — none of it ever knew what a week was
@graview/primitives/workbench; the household app's shell went from 1059 lines to 282
Invariant repairs offer candidate NODES, not a text box asking for an id
packages/tools/src/providers/invariant.ts
graview check understands a lens that binds kinds and edges, not only fields
packages/core/src/cli/check.ts
An action needing several answers asks for them in turn
AnswerArgs
A lens role may bind a FIELD of the kind another role named, and the check verifies it exists there
packages/core/src/cli/check.ts
Coverage can let the GRAPH decide which rows are required, not only a field
requiredVia
The timeline's minimum window is the app's call — a household wants eight hours, two training sessions want two
minWindow
Framework bugs surfaced too, each invisible until an app needed the thing:
jacking in rendered underneath the scene; a coverage cell duplicated a target
already reachable, putting seventy-two extra tab stops between a keyboard user
and the rest of the page; the timeline's window could be centered onto half a
minute and hand the app's own formatter 14:7.5; and a board read its
occupants out of the aggregate, which never contains them, so every slot
reported itself empty.
The four ideas
The graph is the interface. One defineNode() is the source of truth. AI
tool schemas, drag legality, aggregate contents and a11y labels all derive from
it, and every derived value stays inspectable and overridable. Click anything
the interface draws — an event in a calendar, a chip in a list — and you travel
to that node: its neighbors rise onto the plane behind it, each captioned with
the description its edge was declared with ("who does the run", "a nap that
must not be interrupted"). Nobody writes that copy, and a new edge kind shows
up there the moment it is declared.
Actions are derived, not authored. Given a selection, providers contribute
candidates: which mutations are legal across it, which invariants it breaks and
what would repair them, what is structurally true about it. Selecting three
runs where two share a day surfaces "align the third" — because the schema
already said which mutation writes that field, and nobody wrote a rule about
days. An LLM is one optional provider, not the mechanism.
Space is navigable, not decorative. Discrete z-planes with the camera
locked to one axis. Layout is a pure function of (focus, relation, graph)
overlaid with user pins, so the same graph gives the same picture, every stop
is a URL, and any two states interpolate.
Whether it holds is always on screen. The invariant engine runs on every
change and the bar states the result — "All agreements hold", or "2 problems"
that opens what broke and what would fix it. Implicated nodes are marked
wherever they are drawn, including inside a receded group, so a problem never
has to be hunted for. Opening one selects what it names, and the repairs
arrive through the ordinary inspector because repairs already outrank every
other provider there.
An agent you can watch — and take back. Its edits produce the same diffs yours do, so no
bespoke observability is needed for the result — but a diff says what
changed and never what was considered. The tool runtime emits every call as
it happens, reads included, so a turn reads as "looked at the whole graph,
looked at the Tuesday run, moved it to parent1" and every node named in it is
one click away. Any turn can be dropped from the activity rail, keeping
everything since: undoing out of order is legal exactly when no later live op
read something it wrote, so when it is not, the check names what is in the
way and offers to bring it along.
History is a fold, not a stack. The graph is a fold over an append-only
operation log. Every op carries author, batch, intent, its inverse, and the
nodes it READ — which makes "drop the agent's turn, keep my edits" a checkable
dependency condition rather than a stack pop.
What is verified, and how
Nothing below is a claim about intent; each is a test or a measurement.
A focused node surfaces its whole neighborhood, captioned
packages/layout/tests/unit/layout.test.ts
An unanswered argument says what sort of answer it wants
packages/core/tests/unit/mutations.test.ts
The coverage lens works in a domain neither app is about
packages/primitives/tests/unit/coverage.test.tsx — controls against risks
The board lens works in a domain nothing here is about
packages/primitives/tests/unit/board.test.tsx — a seating plan
The framework's own tooling passes the test it sets everyone else
apps/launcher/tests/integration/acceptance.test.ts — the desk declares itself, records its navigation in the log, and can fail its own rules
Nothing the scene places is unreachable, at any viewport
packages/layout/tests/unit/layout.test.ts
Capture + composite works at three depths
docs/spike-three-planes.png, Chrome Canary 154
Clicks land on drawn pixels at every depth
apps/spike/scripts/run-spike.mjs
The shrunk interface is the interface, scaled
scripts/verify-shrunk.mjs — 8 criteria across the example's places in both schemes
The example reaches assistive technology at depth
apps/todo/scripts/run-a11y.mjs — the real accessibility tree through CDP, keyboard order, axe-core
An inbound change is an ordinary op, undoable, authored by the system
packages/core/tests/integration/sync.test.ts
An echo of our own write is recognized and not re-applied
packages/core/tests/integration/sync.test.ts — the loop that breaks naive two-way sync
A conflict is surfaced as a violation with a repair, not resolved silently
packages/core/tests/integration/sync.test.ts
Offline degrades to local-only and reconciles on reconnect
packages/core/tests/integration/sync.test.ts
Traveling changes the address, and back and forward both work
scripts/verify-navigation.mjs — 12 criteria, driven through the controls rather than the keyboard
A stranger can install the tarballs and build a real app
scripts/smoke-install.mjs — packs, installs into a scratch project with no workspace or path mapping, typechecks and runs
graview create makes a project a stranger can install, verify, and use
scripts/smoke-create.mjs — 22 criteria: from the tarballs under npm and pnpm, through create-graview, and by path; the project's own verify; the first hour driven in a browser with axe-core in both schemes
A tarball contains what it should and nothing else
scripts/inspect-pack.mjs — no src, no tests, no tsbuildinfo, and every exports path present
The page that explains this holds up at 320px, to axe-core and to a keyboard, with thirteen live Graviews on it
scripts/verify-site.mjs — 10 widths, both schemes, every chapter mounted and judged, a face switched on the page
An agent seat states what it would do, and goes quiet when there is nothing to do
scripts/verify-seat.mjs — the example's seat; the products run the same harness against theirs
Every skill ends in a check, and names only findings the checker can produce
packages/skills/tests/unit/skills.test.ts — cross-checked against check.ts itself
No card is drawn on top of another, no caption is cut, no control is under a fingertip
scripts/audit-ui.mjs — every state of the examples, measuring what a photograph makes you squint at
What the product apps proved — the port's parity, three seats under one policy, direct manipulation on a board and a calendar, an agent turn watched from altitude
their own repositories, where the same harnesses now run against this repository's sources
The platform, honestly
Read docs/platform-findings.md before trusting
anything about HTML-in-Canvas. The short version, measured in Chrome Canary
154:
Capture and composite work. The API's real call shape is not what the
WICG README describes, and every call sits behind one module.
updateElementGeometry is accepted and does not redirect hit-testing.
PointerRouter supplies that meanwhile, verified at three plane depths.
Accessibility needs no fallback — views stay real, focusable DOM.
Capture costs ~0.016 ms/node up to ~128 live captures a frame, then falls
off a cliff. The fidelity split is load-bearing, not an optimization.
Inline SVG captures fine. Nested canvas and cross-origin frames capture
silently blank, which is worse than throwing.
The site
graview.dev is docs/site, published by GitHub Pages
on every push to main (.github/workflows/pages.yml). The landing page
is the product: the example garden mounted live in the hero and in four
more frames, one per derived surface. The docs are written out of the
repository by scripts/site-docs.mjs — a page per package from its README
and barrel, a page per skill from its SKILL.md, the CLI page from the help
the CLI prints, the findings page from the checker's source, getting
started from what the scaffolder really writes — and tests/site.test.ts
fails when any of it has gone stale. pnpm site:build:all regenerates the
stylesheet, the numbers and the docs (all but the test count, which moves
with every pull request and is filled in by the release's version step and
by the Pages deploy); pnpm site:build rebuilds the
chapters bundle from apps/seedbed; pnpm site drives every page at ten
widths in both schemes with axe-core and a keyboard.
Shipping it
The packages are the deliverable: an SDK someone builds a product on, in
their own repository. Every change to packages/ carries a changeset
(pnpm changeset; CI refuses a pull request without one), and the fourteen
packages are one fixed group, so they share a version and graview create
can pin ^<version> for each of them and name one that exists. On every
push, pnpm pack:inspect says what goes in each tarball and pnpm smoke
proves a stranger can install and build from them; pnpm smoke:create
proves the onboarding in a browser.
.github/workflows/release.yml turns merged changesets into a "Version
packages" pull request, and merging that publishes to npm by trusted
publishing, tags each package, and writes a GitHub release per package.
Status
0.x. The public API is designed to be depended on — clean seams, honest
boundaries — and it will still move between minor versions while the shape
settles; the changelogs say what changed and why.
Outstanding:
Google Calendar has never run against Google. The sync layer is covered
by tests against a scripted remote — echo suppression, conflict detection,
offline reconciliation, and the exact request and response shapes — and the
household product declares its mapping. What no test covers is Google
itself: a token that expires mid-run, a sync token rejected after a week, a
timezone normalized on save and handed back as somebody else's change. The
product's sync-google script is runnable and read-only by default; until
somebody runs it, "works end to end" is a claim rather than a fact.
A screen-reader pass with real assistive technology. The accessibility tree
is populated, every view is exposed by name, the keyboard reaches all three
planes and axe-core reports nothing — but a populated tree is not proof that
VoiceOver reads it well.
License
Elastic License 2.0. Build on it, ship products with it, run it
for your own installations freely; what it withholds is offering Graview
itself as a managed service to third parties, which is what Graview Cloud is.
上次檢查時間：2026-11-15。 Derived affordances and the agent tool surface, generated from the same declarations; graview mcp and graview apply host it against a real store.