graview-embed

graview-embed 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: Put a Graview app on somebody else's page — a picture in an article, a chapter in the docs, a live demo in a landing page — with its own theme scoped to one element, and nothing on the host touched.

Installed into a project by graview skills install ., and read by whichever assistant is working beside you.

The skill

The embed: an app on somebody else's page

@graview/embed mounts an app into any element on any page. It brings its own theme scoped to that element, the brand's fonts, and one app bar — no Shell, no router, nothing of the host's styled or listened to. The same declaration, store and acts as the app; only the frame is the host's.

import { mount } from "@graview/embed";

const handle = mount(el, {
  app, store,                     // or `seed`, and one is made
  views,                          // the app's own registry, in its own schema
  stop: "#focus=agg:plot",        // the fragment the app would put in its address bar
  scheme: "auto",                 // the host's data-theme, else the system's
  label: "Chapter 13",            // names every landmark inside
});
handle.setFace("pages"); handle.setStop("#focus=plot-2"); handle.unmount();

graview create writes this as src/embed.tsx and an embed.html host, so the project's pnpm typecheck covers the embed from day one.

The moves

  1. Say where it opens with the stop, not with code. stop is exactly the fragment the app writes — #overview=1, #focus=agg:plot, #view=the-week — so a link you copied from the app is an embed's starting point. face follows the stop unless you name one.
  2. Pick the face for the page. One app bar: the name and its app menu (Scene, Pages), the place you are on opening the rest (on a wide row they stand, the rest under More), Find, one inbox, the people, the standing, the person. Name no face and an app with a home view opens on it, else the scene; "scene", "graview", "pages" (on path); "picture" is ONE lens alone (stop: "#view=the-week"), no bar. bar: false drops the bar. Under a product's own bar, bar: { faces: false, name: false } (and heading: false) keeps the places, Find, the standing and the person, never CSS hiding them.
  3. Name it. Two embeds on one page carry the same landmarks — the relation key, the inspector, the pages' navigation — and a landmark must be unique by role and name. label names every one of them after the embed.
  4. Let the host decide the look. scheme: "auto" follows the host's data-theme stamp; setScheme follows a host toggle; fonts: false when the host already loads them; brand / setBrand to dress it. Where the host keeps a person's Appearance, `schemeChoice: { value: "system" | "light" | "dark", onChoose }` draws the three in the app menu, the host's value pressed. A press only calls onChoose: keep the choice, stamp data-theme, then `handle.setSchemeChoice({ value, onChoose }) moves the press (undefined` takes it off).
  5. Make the policy felt, if the page is about it. seats lists the principals a reader may take — each a label and a Principal — in the person's menu; the acts and the pages narrow the moment one sits down, and setSeat does it from the host. See graview-permissions.
  6. Many on one page: mount when near. `mountWhenNear(elements, mountOne)` mounts each as the reader scrolls toward it, so a page of sixteen chapters costs one at a time. Share a store only between embeds meant as one app seen twice.
  7. Presence is opt-in. An embed broadcasts nothing and draws nobody unless handed a presence channel: a graph on a page does not tell its readers about each other.
  8. Register only what differs. views(schema, registry) is handed the framework's own view for every cell, with the declaration's viewSpecs already drawn; register onto it the cells you want different, and the rest stay. The same registry draws every face — the gallery's card, the list's row (one × glyph), the record's page (one × full). A view that adds to the default draws it inside itself with <DefaultView {...props} /> (@graview/primitives); on the record page, which is the default, that draws nothing. @graview/embed/pages takes views too.
  9. Say its name at the right level. The bar says the app's name once, as a heading: heading: 1 when the page is the app (and `height: "viewport", re-measured as a phone turns), the default 2` inside an article, false when your heading already says it.
  10. Say your address for a page, or none. Inside your page the app keeps its pages in memory, so /tasks/t1 is no address of yours, and a view's link, a bar's place and the Scene's Open carry no href — a link by its role and the keyboard. Give `hrefOf: (path) => "/notes?open=" + encodeURIComponent(path)` and they carry yours, so Cmd-click opens your page there; open it on that path.

A host whose page IS the app — a service that serves it, a chat's widget, the address bar, its own menu, knowing when a place has drawn, a view proposed and not kept, and pictures of places — is graview-host-page.

A view of your own, in a frame

The other way round: somebody's HTML page drawn inside the app as a view of a kind or as the home, in a frame sandboxed to scripts alone. Register it with guestView from @graview/guest/host:

views.register("package", { cardinality: "many", fidelity: "full" },
  guestView({ url, name: "prices", title: "The price sheet", reads: { kinds: ["offer"], edges: ["includes"] } }),
  { title: "The price sheet" });   // a place on both faces, by its title
views.home(guestView({ url: frontUrl, name: "front", reads: { kinds: ["package"] } }));

The page needs no build. Inline @graview/guest/client.js (or serve it at a path of your own) and connect:

  • GraviewGuest.connect() returns the guest. guest.subscribe(fn) is called with every push of props.
  • props.nodes holds the records it is drawn over and those of the kinds it reads, each with id, kind, label and its fields; props.edges the links among them ({ kind, from, to }). Only what the viewer may see.
  • props.theme is the app's look: scheme, colors, fontDisplay, radius, name, and logo (a data: image; serve with `img-src data:`). Paint from it; it is pushed again when the app's toggle or brand changes, whatever the system prefers.
  • guest.act(name, args) asks for an act; it is applied as the viewer, via: "view:<name>", and resolves { ok, intent } or `{ ok: false, message }, the policy's own sentence. props.acts` lists what they may run.
  • guest.navigate(id) goes to a record; guest.navigate({ place: slug }) to one of props.places.
  • guest.size(px) asks for a height; the frame takes it.

examples/price-sheet.html is a whole one: each package with its offers, painted from the theme, a press that notes something, links to the offers, and its own height. It runs under default-src 'none'; script-src 'unsafe-inline', the policy Graview Cloud serves an uploaded view with.

A worker view (registerWorkerView) runs in a worker the host starts from a blob: URL, so a host page with a Content-Security-Policy says worker-src blob: and style-src 'unsafe-inline'. Without them each view draws its plain face, onFailure hears start naming the directive, and the console says so once. A host that allows no blob: serves viewScript from its own origin and passes worker: { url } (the guest README).

Worked examples

  • apps/seedbed/src/site-embed.ts — the docs site's chapters, many to a page, mounted as the reader nears them, the rota's seats in the person's menu
  • apps/rota/src/embed.ts — two embeds of one app on one host page, each named for what it shows
  • packages/core/src/scaffold/ui.ts — what graview create writes

Then find out whether it worked

pnpm build && npx graview check ./dist/domain/app.js   # the declaration is still whole
pnpm typecheck                                          # the embed takes the app's own views, no casts

Then open the host page at a phone's width and with two embeds on it: each names its own landmarks, neither pushes the page sideways, and pressing a place in one moves only that one. packages/embed/tests/unit/embed.test.ts holds the contracts; copy its shape for a host of your own.

What the check cannot see

  • Whether the host's CSS reaches in. The embed scopes its own theme, and every rule of it stays inside its element, so the host's own buttons, headings and code keep the host's look; but a host rule like button { … } on the whole page still applies inside the embed, and only looking at the page finds it.
  • Whether the stop still lands. A stop names ids and places; rename a place or seed different ids and an embed opens somewhere it resolves to rather than where the article says it does.