@graview/guest 0.1.9 → 0.1.10

package/README.md

@@ -57,7 +57,67 @@ entries import nothing of the framework, so a guest bundle carries none of it.
 `GuestProps` is the plain-data half of `ViewProps` — `node`, `nodes`, the
 `edges` among them, `label`, `fidelity`, `cardinality`, `mode`, `selected`,
 `implicated`, `flagged` — and `acts`, the acts the viewer may run. A record
-the viewer may not see is in none of them.
+the viewer may not see is in none of them. Every record's `label` is
+filled as the host labels it, and `theme` and `places` are the app's.
+
+### What a frame guest reads, its look, and its place
+
+```ts
+views.register("package", { cardinality: "many", fidelity: "full" },
+  guestView({ url, name: "prices", title: "The price sheet", reads: { kinds: ["offer"], edges: ["includes"] } }),
+  { title: "The price sheet" });
+views.home(guestView({ url: frontUrl, name: "front", reads: { kinds: ["package"] } }));
+```
+
+A guest is handed what it is drawn over and the edges among those records.
+With `reads` it is also handed every record of the kinds it reads and
+every edge of the edges it reads between the records it holds, as the
+viewer sees them (`readAcross`, the rule a worker view's manifest uses
+too). A guest over packages that reads `offer` and `includes` gets each
+package's offers, and an offer the viewer may not see is in none of it.
+Drawn as the home (`views.home`), a guest is drawn over nothing and sees
+what it reads: it is the routed home's body, and the landing over the scene.
+
+Its props carry `theme`, a `GuestTheme`: the scheme, the accent, ground,
+panel, ink, muted ink and edge colours, and the body and mono fonts, read
+off the element the frame is drawn in. The scheme is the app's own (the
+embed's `data-graview-scheme`), not the system's, and the host pushes
+again when the app's toggle changes it. `mountGuestView` takes `reads`,
+`theme` and `places` too.
+
+`title` names the frame for assistive technology. Registered with the same
+title, the guest is a place on both faces: listed by `placesOf`, at
+`/places/the-price-sheet` on the routed face and `#view=the-price-sheet` in
+the scene. `props.places` lists the app's places, and
+`guest.navigate({ place: "the-packages" })` goes to one.
+
+### One client, served or inlined
+
+`@graview/guest/client.js` is the frame guest's client as one prebuilt
+classic script (2.4 kB). It leaves one global, `GraviewGuest`, and
+`GraviewGuest.connect()` is `connectGuest()`. A host serves it at a path of
+its own, or inlines its text where a frame's policy allows inline script
+alone, as Graview Cloud serves an uploaded view (`script-src
+'unsafe-inline'`). `GUEST_CLIENT` from `@graview/guest/client` is that
+text, and `GUEST_CLIENT_SHA256` its hash for a policy that names it.
+
+```html
+<main id="app"></main>
+<script>/* GUEST_CLIENT */</script>
+<script>
+  const guest = GraviewGuest.connect();
+  guest.subscribe((props) => {
+    document.body.style.background = props.theme.panel;
+    app.replaceChildren(...props.nodes.map((node) => Object.assign(document.createElement("p"), { textContent: node.label })));
+    guest.size(document.documentElement.scrollHeight);
+  });
+</script>
+```
+
+How to write one, with a worked example, is the `graview-embed` skill.
+`guest-sandbox --transport=client` serves a guest of a few lines under that
+policy and finds it renders, acts, navigates, resizes and follows the
+app's toggle in Chromium, WebKit and Firefox.
 
 ## In a worker
 
@@ -84,7 +144,11 @@ limits. A second ready from the same worker is dropped. Once it is ready,
 the host sends a heartbeat over the port and the worker's runtime answers
 it; a worker that goes `limits.silentMs` (5 000 by default) without an
 answer — a guest spinning in `while (true)` — is terminated, and
-the host is told `silent`. A guest that is busy but yields is kept. What the guest draws
+the host is told `silent`. A guest that is busy but yields is kept. The
+host also counts its own time drawing what the guest sends. Over any one
+second it spends at most `limits.drawMs` (100 by default). Past it, the
+rest of the batch is left undrawn, the worker is terminated, and the host
+is told `slow`. What the guest draws
 comes over the port as Remote DOM mutation records, and the host draws only
 the kit (`GUEST_KIT`), with `createKitRenderer`. Both are
 `@graview/guest/host/worker`, apart from the frame's host, so a page that
@@ -144,3 +208,238 @@ runs guests it did not build checks them, or better, builds them itself.
 
 The worker entry carries Remote DOM (`@remote-dom/core` and its polyfill,
 MIT, pinned); the frame guest and the host do not.
+
+## A worker view on the open kit
+
+A view that needs more than the kit's components — a card grid, a chart,
+an animated ring — draws plain HTML, SVG and one stylesheet instead. What
+keeps it safe is what it can reach, not what it can draw: it runs in the
+same hardened classic worker, and the host draws what it says into a
+shadow root inside a region of the host's own — `contain: layout paint
+style`, `isolation: isolate`, `overflow: clip` — keeping only what the open
+kit allows. The view is one plain script with no imports and no build;
+the host puts the view's runtime in front of it.
+
+```ts
+import { mountWorkerView } from "@graview/guest/host/worker";
+
+const view = mountWorkerView(element, { manifest, worker: { source }, store, principal,
+  onFailure: (reason, detail) => showTheTierOneFace(reason, detail) });
+```
+
+In the worker, the view has one global, `graview`:
+
+```js
+graview.style(`.grid { display: grid; gap: 12px } .card { background: var(--graview-panel) }`);
+graview.onProps((props) => graview.render(graview.html`
+  <section class="grid">${props.nodes.map((n) => graview.html`<article class="card"><h3>${n.label}</h3></article>`)}</section>`));
+graview.on("click", ".card", (event) => { /* … */ });
+```
+
+What may be drawn is one declaration, read by both sides: most of HTML's
+sectioning, text, lists, tables, `details`, buttons, fields and `img`;
+SVG's shapes, paths, text, gradients, clip paths, masks, markers and `use`
+of `#id`; and CSS for layout, grid, flex, colour, type, transitions,
+keyframes, media and container queries, with the app's theme tokens
+(`--graview-*`) inherited, light or dark as the app is. The stylesheet,
+every `style` attribute and every SVG paint are read with the CSS Syntax
+tokenizer and parser — escapes decoded, comments gone — and written afresh
+from what was kept: `url()` only as `url(#id)` on a paint, no `@import`,
+`@font-face` or other at-rule but `@media`, `@supports`, `@container` and
+`@keyframes`, only the functions on the list (no `image-set()`, `attr()`,
+`cross-fade()`, `element()` …), `position` only static, relative or
+absolute, and no selector that reaches out of the shadow tree (`:host`,
+`::slotted`). An image is a `data:` image or a `blob:` of the page's own;
+an SVG image in an `img` runs no script and loads nothing. No `<script>`,
+`<iframe>`, `<object>`, `<embed>`, `<link>`, `<meta>`, `<base>`, `<style>`,
+`<form>`, SVG `<image>` or `<foreignObject>`, no `src`, `href`, `srcset`,
+`formaction` or `on*` attribute is drawn; what is not drawn is in
+`refused`, with why. A view never speaks as the app's chrome. `<nav>`,
+`<header>`, `<footer>`, `<aside>` and `<search>` are drawn as `<div>`, and
+`<output>` as `<span>`. Each holds what it held and is marked
+`data-graview-as`, and the view's selectors for those names are read as
+that attribute. A `<section>` is never named, and `role` takes no landmark
+or notice's role. `guest-sandbox --transport=open` serves a page with no
+content security policy, tries every way out, and finds no request leaving
+it in Chromium, WebKit or Firefox.
+
+### A worker view is a place
+
+A worker view says what it is and what it may touch in a manifest the host
+enforces:
+
+```ts
+import { registerWorkerView, workerHome } from "@graview/guest/host/views";
+
+const packages = {
+  manifest: { name: "packages", title: "The packages", attach: "package", cardinality: "many",
+    reads: { kinds: ["offer"], edges: ["includes"] }, acts: ["set-standing"] },
+  worker: { source },
+  author: "Made by Claude for Nick",
+};
+views: (schema, registry) => registerWorkerView(registry, packages),   // the embed's views
+pages.surface("home", workerHome(frontPage));                         // a view of the home
+```
+
+It is handed the viewer's sight and nothing more, cut to the kind it
+attaches to (the members the face hands it, or every one the viewer sees)
+and the kinds and edges it reads: a record the viewer may not see is in
+none of it, and a kind it did not ask to read is not handed to it however
+visible. Every record's `label` is filled as the host labels it — for a
+frame guest too. A titled view is a named place on the Graview face and
+the pages face, by its title; whatever the registry drew for that kind
+before is drawn if the view fails. With `attach: "home"`,
+`registerWorkerView` makes it the home's own view (FR-81). That is the
+routed home's body and the landing over the scene when it is at home, in
+place of the home the app declared, which is drawn if the view fails.
+`workerHome` makes it the routed face's whole home surface instead. Its props carry the app's look as a
+`GuestTheme` — the scheme, the accent, ground, panel, ink, muted ink and
+edge colours, and the body and mono fonts — read off the region it is
+drawn in, and the host
+pushes again when the app's own toggle changes the scheme, whatever the
+system prefers. `checkManifest` says what in a manifest names a kind, an
+edge or an act the app does not declare, and the host refuses to start
+such a view (`onFailure` hears `manifest`).
+
+### Writes that cannot leak
+
+A view runs for every member with that member's sight, and its author is
+not the member, so the danger is a view reading what this viewer may see
+and writing it where somebody else may. An act must be named in the
+manifest. Where the app's sight is total — no sight is declared, or every
+kind is seen whole by everybody (`sightIsTotal`) — an act the view asks for
+from its code applies with its arguments as given. Otherwise it applies
+only from a press the host itself saw:
+
+```html
+<fieldset>
+  <input name="summary" placeholder="What it is">
+  <button data-act="set-summary" data-record="package:start">Say it</button>
+</fieldset>
+```
+
+A trusted click on an element with `data-act` is judged and applied in the
+click's own handler, before the view hears of it (it hears `pressed`). Its
+arguments come only from the record the element is bound to (`data-record`,
+one the view was shown), the manifest's constants for the act (`{ act,
+as, constants }`), and the fields in the press's `fieldset` the host read
+itself — each one the viewer's: its last change a trusted `input`, and
+nothing the view wrote in it since. A field the view filled is the view's
+until the viewer empties it; a `change` a browser raises when such a field
+loses focus is not typing; a view that says back what a field shows, or
+empties it, takes nothing away. Either way an act is applied as the viewer,
+`via: "view:<name>"`, within the view's allowance, and undoable.
+
+### Links stay in the app
+
+A worker view links to a record or a named place of this app, and nowhere
+else. The open kit draws no `href`, so `<a href="https://…">` is text;
+`<a data-record="offer:coaching">` and `<a data-place="the-packages">` are
+made links by the host — focusable, a link to assistive technology — and
+followed by it on a press or Enter, to a record the viewer may see or a
+place the app has. `graview.navigate("offer:coaching")` and
+`graview.navigate({ place: "the-packages" })` are held to the same. The
+props list the app's places (`places`, each with its slug and title). On
+the Graview face a record is focused and chosen and a place is drawn; on
+the pages face each goes to its own address — through `useGoTo` in
+`@graview/react`, which the routed face provides. The kit's `gv-link`
+keeps `links.origins`: it is the kit's one deliberate way out, to the
+origins a host lists, and an open-kit view has none.
+
+### Limits, and what is drawn in a view's place
+
+The host caps a view's code (`maxSourceBytes`, 256 000 by default), the
+nodes it draws (`maxNodes`, 5 000), the messages it sends (`messages` in
+`messageWindowMs`, 120 a second) and the time it takes over each push of
+what it is shown (`pushMs`, 1 000 ms: the view's listeners as its runtime
+times them, and the wait for the runtime to say it drew, as the host times
+it), beside the heartbeat's `silentMs`, and the page's own time drawing
+what the view sends (`drawMs`, 100 ms of any second). Past any of them the worker is
+terminated, the plain face of what the view was shown — its title and each
+record by its label, drawn by the host — is drawn in the region, and
+`onFailure` hears why: `source`, `nodes`, `flood`, `slow`, `silent`,
+`error` (it threw before it drew), `refused` or `manifest`, with a sentence
+saying it. A host draws its own in its place with `fallback`; the React
+registrations draw whatever the registry drew for the kind before.
+
+What is left: work a view schedules with timers between pushes is not
+timed per push. A view that busies its own worker for just under
+`silentMs`, answers the heartbeat, and does it again can hold a core of the
+reader's machine for as long as it is shown. That is the worker's thread,
+not the page's; the page stays responsive.
+
+### A view with no build
+
+A view is handed over as its plain source, `{ source }`: one script
+against the `graview` global, with no imports, no bundler and no copy of
+the protocol. The host puts the view's runtime in front of it — Remote
+DOM's polyfill, the hardening, the channel and the global, which the host
+holds as one classic script and fetches only when it first starts a view —
+and runs both as one strict classic worker. A module worker is not an
+option: a `blob:` one is refused in an opaque origin. The hardened worker
+has no `eval`, no function constructor and no `importScripts`, so the one
+way left to load code is `import()`, which is syntax: a source whose text
+says `import` anywhere, even in a string or a comment, is refused before it
+runs (`checkViewSource` says why), and so is one that exports. `{ script }`
+still takes a whole worker script built against `@graview/guest/worker/view`.
+How to write one — the manifest, what may be drawn, the theme's tokens, the
+write rules, links and limits, with a list lens and a home worked through —
+is the `graview-worker-view` skill (`graview skills install`).
+
+### Run a view headless, and say what it drew
+
+Before a view is applied, a host can run it once with no network and no
+DOM, against one member's sight, and be told what it drew in the words
+`describePlace` says a place in (`@graview/core/describe`): its headings,
+text, figures and fields, and its lists with each record's title and what
+its row or card says. Or it is told why the view will not do.
+
+```ts
+import { runWorkerViewHeadless } from "@graview/guest/headless";
+
+const result = await runWorkerViewHeadless({ manifest, source, store, principal, run });
+if (result.ok) say(result.description.text);       // "The packages (/places/the-packages) — as partner …"
+else say(result.reason, result.detail);            // "act": It asks for the act "buy", which its manifest does not name.
+```
+
+The reasons are the page's (`source`, `manifest`, `error`, `nodes`,
+`flood`, `slow`, `refused`) and two of a headless run's own: `act`, an act
+asked for from the view's code or bound to a press (`data-act`) that its
+manifest does not name, and `isolate`, the host's isolate could not run it.
+Nothing is applied: an act the view asks for is written down in the
+transcript and answered with a refusal.
+
+A view never runs in the host's own context. The host supplies the
+isolate: `run` is handed one script and one JSON string (`HeadlessPayload`),
+loads the script into an isolate of its choosing, calls the global it
+leaves (`graviewHeadless`) with the string, and hands back the string it
+resolves with. Nothing but text crosses. There is no default, and without
+a `run` the helper throws. The script is the headless runtime, then the
+view. It makes the isolate a worker's before the view is read: the same
+`graview` global over a transcript, a console that writes to it, timers
+that never fire, and everything outside the worker's allowlist taken from
+the global. Then the view's top line runs and it is pushed what it is
+shown, once. What it sent is judged again in the host's context, from the
+transcript alone, by the open kit's own renderer drawing into a tree of
+plain objects (`drawTranscript`, `describeDrawing`), so the isolate's word
+is not taken for what the view drew.
+
+`nodeIsolate` from `@graview/guest/headless/node` is a `run` for Node: a
+worker thread with a heap ceiling and a context made from nothing (no
+`process`, `require`, `fetch` or timers; no code from strings), with a
+deadline that covers the microtasks the view queues. In workerd, the
+script is one module of a worker of its own with no outbound network, and
+the host's module, loaded first, keeps `Response` to answer with:
+
+```js
+// before.js
+const Made = Response; export const answer = (text) => new Made(text);
+// host.js
+import { answer } from "./before.js"; import "./view.js";   // view.js is payload.script
+const run = globalThis.graviewHeadless;
+export default { async fetch(request) { return answer(await run(await request.text())); } };
+```
+
+`graview view check view.js --app app.js --manifest manifest.json --seed
+seed.json --roles partner` does the same from a terminal, with
+`nodeIsolate`.

package/client.js

@@ -0,0 +1,2 @@
+/*! @graview/guest/client.js — a frame guest's client (GraviewGuest.connect). Generated from src/client-script.ts. Elastic License 2.0. */
+"use strict";var GraviewGuest=(()=>{var f=Object.defineProperty;var R=Object.getOwnPropertyDescriptor;var O=Object.getOwnPropertyNames;var H=Object.prototype.hasOwnProperty;var k=(o,t)=>{for(var r in t)f(o,r,{get:t[r],enumerable:!0})},M=(o,t,r,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of O(t))!H.call(o,a)&&a!==r&&f(o,a,{get:()=>t[a],enumerable:!(i=R(t,a))||i.enumerable});return o};var P=o=>M(f({},"__esModule",{value:!0}),o);var T={};k(T,{connect:()=>w,protocol:()=>y});var y=1;function G(o){let t=o;return typeof o=="object"&&o!==null&&t.graview==="host-hello"&&typeof t.nonce=="string"}function b(o,t={}){let r,i="",a,h=0,u=new Set,g=new Map,m=[],d=n=>{r?r.postMessage({...n,nonce:i}):m.push(n)},x=n=>{let e=n.data;if(!(!e||typeof e!="object")){if(e.type==="props"){a=e.props;for(let s of u)s(e.props)}else e.type==="answer"?(g.get(e.id)?.(e),g.delete(e.id)):e.type==="event"&&typeof e.listener=="number"?t.onEvent?.(e):e.type==="heartbeat"&&typeof e.beat=="number"&&d({type:"heartbeat",beat:e.beat});t.onMessage?.(e)}},p=()=>{},E=n=>{if(r||!o.fromHost(n)||!G(n.data)||n.data.protocol!==1)return;let e=n.ports[0];if(e){r=e,i=n.data.nonce,r.onmessage=x,r.start?.(),p();for(let s of m.splice(0))d(s)}};p=o.listen(E),o.ready({graview:"guest-ready",protocol:1});let c,v={get props(){return a},subscribe(n){return u.add(n),()=>u.delete(n)},act(n,e={}){let s=h+=1;return new Promise(l=>{g.set(s,l),d({type:"act",id:s,name:n,args:e})})},navigate(n){typeof n=="string"?d({type:"navigate",to:n}):n&&typeof n.place=="string"&&d({type:"navigate",place:n.place})},size(n){d({type:"size",height:n})},autoSize(n){let e=n??globalThis.document?.documentElement,s=globalThis.ResizeObserver;if(!e||!s||typeof e.getBoundingClientRect!="function")return()=>{};c?.disconnect();let l=new s(()=>v.size(Math.ceil(e.getBoundingClientRect().height)));return l.observe(e),c=l,()=>l.disconnect()},close(){c?.disconnect(),p(),r?.close(),u.clear()}};return{guest:v,send:d}}function w(o={}){let t=o.window??globalThis;return b({listen(r){return t.addEventListener("message",r),()=>t.removeEventListener("message",r)},fromHost:r=>r.source===t.parent&&(o.hostOrigin===void 0||r.origin===o.hostOrigin),ready:r=>t.parent?.postMessage(r,"*")}).guest}return P(T);})();

package/dist/channel.d.ts

@@ -1,4 +1,4 @@
-import { type GuestAnswer, type GuestEvent, type GuestProps, type GuestRequest } from "./protocol.js";
+import { type GuestAnswer, type GuestEvent, type GuestProps, type GuestRequest, type HostMessage } from "./protocol.js";
 /**
  * A GUEST'S ONE CHANNEL to the host that started it. It can read what the
  * host pushed and ask; it cannot reach the store, and an act it asks for
@@ -11,8 +11,14 @@ export interface Guest {
     subscribe(listener: (props: GuestProps) => void): () => void;
     /** Ask for an act by name. Resolves with the host's answer; never rejects for a refusal. */
     act(name: string, args?: Readonly<Record<string, unknown>>): Promise<GuestAnswer>;
-    /** Ask the host to go to a record. A record the viewer may not see goes nowhere. */
-    navigate(to: string): void;
+    /**
+     * Ask the host to go to a record, by its id, or to one of the app's named
+     * places (`{ place: slug }`, one `props.places` lists). A record the viewer
+     * may not see, and a place the app does not have, go nowhere.
+     */
+    navigate(to: string | {
+        readonly place: string;
+    }): void;
     /** Ask for a height, in CSS pixels. */
     size(height: number): void;
     /** Ask for the height of an element whenever it changes. Returns the stop. In a worker, where nothing is laid out, it does nothing. */
@@ -44,6 +50,8 @@ export interface GuestLink {
  */
 export declare function openGuest(link: GuestLink, hooks?: {
     readonly onEvent?: (event: GuestEvent) => void;
+    /** Every message from the host, once the channel's own handling of it is done: a runtime's way to hear what is its own (FR-90). */
+    readonly onMessage?: (message: HostMessage) => void;
 }): {
     readonly guest: Guest;
     send(request: Unsent): void;

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EAElB,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACpB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;IACvC,uDAAuD;IACvD,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC7D,4FAA4F;IAC5F,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAClF,oFAAoF;IACpF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,uCAAuC;IACvC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,uIAAuI;IACvI,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI,CAAC;IACxC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,+CAA+C;AAC/C,MAAM,MAAM,MAAM,GAAG,YAAY,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,YAAY,GAAG,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;AAEhH;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACzD,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;IACvC,iBAAiB;IACjB,KAAK,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACtF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,GAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;CAAO,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAwFjK"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACpB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;IACvC,uDAAuD;IACvD,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC7D,4FAA4F;IAC5F,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAClF;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACxD,uCAAuC;IACvC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,uIAAuI;IACvI,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI,CAAC;IACxC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,+CAA+C;AAC/C,MAAM,MAAM,MAAM,GAAG,YAAY,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,YAAY,GAAG,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;AAEhH;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACzD,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;IACvC,iBAAiB;IACjB,KAAK,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACtF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,EACf,KAAK,GAAE;IACL,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC/C,mIAAmI;IACnI,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;CAChD,GACL;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CA0FxD"}

package/dist/channel.js

@@ -38,6 +38,7 @@ export function openGuest(link, hooks = {}) {
             /* The runtime answers, so only a blocked event loop goes quiet. */
             send({ type: "heartbeat", beat: message.beat });
         }
+        hooks.onMessage?.(message);
     };
     let stop = () => { };
     const hello = (event) => {
@@ -77,7 +78,10 @@ export function openGuest(link, hooks = {}) {
             });
         },
         navigate(to) {
-            send({ type: "navigate", to });
+            if (typeof to === "string")
+                send({ type: "navigate", to });
+            else if (to && typeof to.place === "string")
+                send({ type: "navigate", place: to.place });
         },
         size(height) {
             send({ type: "size", height });

package/dist/channel.js.map

@@ -1 +1 @@
-{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `graview view check` — run a worker view once, headless, and say what it
+ * drew (FR-95).
+ *
+ * The view's source, its manifest, the app it is for and, given one, a seed
+ * to run it over, seated as one member: it runs in a worker thread's fresh
+ * context with no network (`@graview/guest/headless/node`) and the command
+ * prints what it drew in the words `graview describe` says a place in, or
+ * why it will not do. Exit 0 when it drew, 1 when it will not do.
+ *
+ * Reached through the `graview` command line, which dispatches here; this
+ * package ships no bin of its own.
+ */
+export declare const VIEW_USAGE = "  graview view check <view.js> --app <app> --manifest <manifest.json>\n                     [--seed <file>] [--as <id>] [--roles a,b] [--width <px>] [--json]\n      run a worker view once, headless, with no network, seated as one\n      member (the system, unless --as or --roles say who), and say what it\n      drew, or why it will not do\n";
+export declare function view(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,UAAU,2VAKtB,CAAC;AASF,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2CnE"}

package/dist/cli.js

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { Store } from "@graview/core";
+import { loadApp } from "@graview/core/cli";
+import { runWorkerViewHeadless } from "./headless/index.js";
+import { nodeIsolate } from "./headless/node.js";
+/**
+ * `graview view check` — run a worker view once, headless, and say what it
+ * drew (FR-95).
+ *
+ * The view's source, its manifest, the app it is for and, given one, a seed
+ * to run it over, seated as one member: it runs in a worker thread's fresh
+ * context with no network (`@graview/guest/headless/node`) and the command
+ * prints what it drew in the words `graview describe` says a place in, or
+ * why it will not do. Exit 0 when it drew, 1 when it will not do.
+ *
+ * Reached through the `graview` command line, which dispatches here; this
+ * package ships no bin of its own.
+ */
+export const VIEW_USAGE = `  graview view check <view.js> --app <app> --manifest <manifest.json>
+                     [--seed <file>] [--as <id>] [--roles a,b] [--width <px>] [--json]
+      run a worker view once, headless, with no network, seated as one
+      member (the system, unless --as or --roles say who), and say what it
+      drew, or why it will not do
+`;
+function flag(argv, name) {
+    const at = argv.indexOf(name);
+    return at === -1 ? undefined : argv[at + 1];
+}
+const readJson = (file) => JSON.parse(readFileSync(resolve(process.cwd(), file), "utf8"));
+export async function view(argv) {
+    const [command, file] = argv;
+    if (command !== "check" || !file || file.startsWith("--")) {
+        process.stdout.write(`graview view — a worker view, run where it can reach nothing\n\n${VIEW_USAGE}`);
+        return command === undefined || command === "help" || command === "--help" ? 0 : 1;
+    }
+    const appAt = flag(argv, "--app");
+    const manifestAt = flag(argv, "--manifest");
+    if (!appAt || !manifestAt) {
+        process.stderr.write(`graview view check needs --app and --manifest.\n\n${VIEW_USAGE}`);
+        return 1;
+    }
+    const app = await loadApp(appAt);
+    const seedAt = flag(argv, "--seed");
+    const store = new Store({
+        schema: app.schema,
+        mutations: (app.mutations ?? []),
+        ...(app.policy ? { policy: app.policy } : {}),
+        ...(seedAt ? { snapshot: readJson(seedAt) } : {}),
+    });
+    const roles = (flag(argv, "--roles") ?? "").split(",").map((role) => role.trim()).filter(Boolean);
+    const as = flag(argv, "--as");
+    const principal = as || roles.length > 0 ? { kind: "human", id: as ?? "graview-view-check", ...(roles.length > 0 ? { roles } : {}) } : { kind: "system", id: "graview-view-check" };
+    const width = flag(argv, "--width");
+    const result = await runWorkerViewHeadless({
+        store,
+        principal,
+        manifest: readJson(manifestAt),
+        source: readFileSync(resolve(process.cwd(), file), "utf8"),
+        run: nodeIsolate(),
+        places: (app.views?.places?.() ?? []).map((place) => ({ as: place.as, title: place.title, kind: place.kind })),
+        ...(width ? { width: Number(width) } : {}),
+    });
+    if (argv.includes("--json")) {
+        process.stdout.write(`${JSON.stringify(result.ok ? result.description : { reason: result.reason, detail: result.detail }, null, 2)}\n`);
+        return result.ok ? 0 : 1;
+    }
+    if (!result.ok) {
+        process.stdout.write(`${file} will not do (${result.reason}): ${result.detail}\n`);
+        return 1;
+    }
+    process.stdout.write(`${result.description.text}\n`);
+    return 0;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/client-script.d.ts

@@ -0,0 +1,3 @@
+export { connectGuest as connect } from "./guest.js";
+export { GUEST_PROTOCOL as protocol } from "./protocol.js";
+//# sourceMappingURL=client-script.d.ts.map

package/dist/client-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-script.d.ts","sourceRoot":"","sources":["../src/client-script.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,YAAY,IAAI,OAAO,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,cAAc,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/client-script.js

@@ -0,0 +1,21 @@
+/*
+ * THE FRAME GUEST'S CLIENT, AS ONE CLASSIC SCRIPT (FR-88).
+ *
+ * `connectGuest` is a module, so every frame guest bundled or inlined its
+ * own copy. This is the entry `scripts/guest-view-runtime.mjs` bundles into
+ * `client.js` at the package's root — `@graview/guest/client.js`, an IIFE
+ * that leaves one global, `GraviewGuest`:
+ *
+ *   const guest = GraviewGuest.connect();
+ *   guest.subscribe((props) => draw(props));       // nodes, edges, acts, theme, places
+ *   guest.act("add-note", { label: "…" });         // the viewer's act, answered
+ *   guest.navigate("offer:7");                     // or { place: "the-packages" }
+ *   guest.autoSize();                              // or guest.size(px)
+ *
+ * A host serves it at a fixed path of its own, or inlines its text
+ * (`GUEST_CLIENT`, from `@graview/guest/client`) where a frame's policy
+ * allows inline script alone.
+ */
+export { connectGuest as connect } from "./guest.js";
+export { GUEST_PROTOCOL as protocol } from "./protocol.js";
+//# sourceMappingURL=client-script.js.map

package/dist/client-script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-script.js","sourceRoot":"","sources":["../src/client-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,YAAY,IAAI,OAAO,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,cAAc,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+export { GUEST_CLIENT, GUEST_CLIENT_SHA256 } from "./client.generated.js";
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/client.generated.d.ts

@@ -0,0 +1,4 @@
+export declare const GUEST_CLIENT: string;
+/** For `script-src 'sha256-…'`. */
+export declare const GUEST_CLIENT_SHA256: string;
+//# sourceMappingURL=client.generated.d.ts.map

package/dist/client.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.generated.d.ts","sourceRoot":"","sources":["../src/client.generated.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,YAAY,EAAE,MAA+5E,CAAC;AAC37E,mCAAmC;AACnC,eAAO,MAAM,mBAAmB,EAAE,MAA8D,CAAC"}

package/dist/client.generated.js

@@ -0,0 +1,9 @@
+/*
+ * GENERATED by scripts/guest-view-runtime.mjs from src/client-script.ts — do not edit.
+ * The frame guest's client as one classic script (FR-88), as text a host
+ * inlines, and its hash for a policy that names it.
+ */
+export const GUEST_CLIENT = "/*! @graview/guest/client.js — a frame guest's client (GraviewGuest.connect). Generated from src/client-script.ts. Elastic License 2.0. */\n\"use strict\";var GraviewGuest=(()=>{var f=Object.defineProperty;var R=Object.getOwnPropertyDescriptor;var O=Object.getOwnPropertyNames;var H=Object.prototype.hasOwnProperty;var k=(o,t)=>{for(var r in t)f(o,r,{get:t[r],enumerable:!0})},M=(o,t,r,i)=>{if(t&&typeof t==\"object\"||typeof t==\"function\")for(let a of O(t))!H.call(o,a)&&a!==r&&f(o,a,{get:()=>t[a],enumerable:!(i=R(t,a))||i.enumerable});return o};var P=o=>M(f({},\"__esModule\",{value:!0}),o);var T={};k(T,{connect:()=>w,protocol:()=>y});var y=1;function G(o){let t=o;return typeof o==\"object\"&&o!==null&&t.graview===\"host-hello\"&&typeof t.nonce==\"string\"}function b(o,t={}){let r,i=\"\",a,h=0,u=new Set,g=new Map,m=[],d=n=>{r?r.postMessage({...n,nonce:i}):m.push(n)},x=n=>{let e=n.data;if(!(!e||typeof e!=\"object\")){if(e.type===\"props\"){a=e.props;for(let s of u)s(e.props)}else e.type===\"answer\"?(g.get(e.id)?.(e),g.delete(e.id)):e.type===\"event\"&&typeof e.listener==\"number\"?t.onEvent?.(e):e.type===\"heartbeat\"&&typeof e.beat==\"number\"&&d({type:\"heartbeat\",beat:e.beat});t.onMessage?.(e)}},p=()=>{},E=n=>{if(r||!o.fromHost(n)||!G(n.data)||n.data.protocol!==1)return;let e=n.ports[0];if(e){r=e,i=n.data.nonce,r.onmessage=x,r.start?.(),p();for(let s of m.splice(0))d(s)}};p=o.listen(E),o.ready({graview:\"guest-ready\",protocol:1});let c,v={get props(){return a},subscribe(n){return u.add(n),()=>u.delete(n)},act(n,e={}){let s=h+=1;return new Promise(l=>{g.set(s,l),d({type:\"act\",id:s,name:n,args:e})})},navigate(n){typeof n==\"string\"?d({type:\"navigate\",to:n}):n&&typeof n.place==\"string\"&&d({type:\"navigate\",place:n.place})},size(n){d({type:\"size\",height:n})},autoSize(n){let e=n??globalThis.document?.documentElement,s=globalThis.ResizeObserver;if(!e||!s||typeof e.getBoundingClientRect!=\"function\")return()=>{};c?.disconnect();let l=new s(()=>v.size(Math.ceil(e.getBoundingClientRect().height)));return l.observe(e),c=l,()=>l.disconnect()},close(){c?.disconnect(),p(),r?.close(),u.clear()}};return{guest:v,send:d}}function w(o={}){let t=o.window??globalThis;return b({listen(r){return t.addEventListener(\"message\",r),()=>t.removeEventListener(\"message\",r)},fromHost:r=>r.source===t.parent&&(o.hostOrigin===void 0||r.origin===o.hostOrigin),ready:r=>t.parent?.postMessage(r,\"*\")}).guest}return P(T);})();\n";
+/** For `script-src 'sha256-…'`. */
+export const GUEST_CLIENT_SHA256 = "sha256-3FZdxG7Qo/vAIcKcV2ujTNB3AGU+ASH0aHfbjDVzECQ=";
+//# sourceMappingURL=client.generated.js.map

package/dist/client.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.generated.js","sourceRoot":"","sources":["../src/client.generated.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAW,s5EAAs5E,CAAC;AAC37E,mCAAmC;AACnC,MAAM,CAAC,MAAM,mBAAmB,GAAW,qDAAqD,CAAC"}

package/dist/client.js

@@ -0,0 +1,12 @@
+/*
+ * THE FRAME GUEST'S CLIENT, AS TEXT A HOST CAN INLINE (FR-88):
+ * `@graview/guest/client`.
+ *
+ * `@graview/guest/client.js` is the client as a file, for a host that
+ * serves it at a path of its own. Where a frame's policy allows inline
+ * script alone (`script-src 'unsafe-inline'`, as Graview Cloud serves an
+ * uploaded view), a host puts this text in a `<script>` of the frame's page
+ * instead, or names its hash in the policy (`script-src 'sha256-…'`).
+ */
+export { GUEST_CLIENT, GUEST_CLIENT_SHA256 } from "./client.generated.js";
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/headless/describe.d.ts

@@ -0,0 +1,19 @@
+import type { DescribedPart, DescribedProblem } from "@graview/core/describe";
+import type { GuestProps } from "../protocol.js";
+import { TreeElement } from "./tree.js";
+export interface DescribeDrawingContext {
+    /** What the view was shown: a record a link or a row names is looked up here, and only here. */
+    readonly props: GuestProps;
+    /** The app's places, by slug: where a `data-place` may point. */
+    readonly places: readonly string[];
+}
+export interface DescribedDrawing {
+    readonly parts: readonly DescribedPart[];
+    readonly problems: readonly DescribedProblem[];
+    /** The acts the drawing binds a press to (`data-act`), each once. */
+    readonly acts: readonly string[];
+    /** The records it binds or links to (`data-record`), each once. */
+    readonly records: readonly string[];
+}
+export declare function describeDrawing(root: TreeElement, context: DescribeDrawingContext): DescribedDrawing;
+//# sourceMappingURL=describe.d.ts.map

package/dist/headless/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../../src/headless/describe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,aAAa,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC7F,OAAO,KAAK,EAAa,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAA2B,MAAM,WAAW,CAAC;AAoBjE,MAAM,WAAW,sBAAsB;IACrC,gGAAgG;IAChG,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AA8BD,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,gBAAgB,CAiNpG"}