@graview/core 0.1.0

package/dist/scaffold/ui.js

@@ -0,0 +1,536 @@
+import { escapeHtml, escapeString, escapeTemplate } from "./names.js";
+/*
+ * THE FACES A NEW PROJECT HAS: the page, the embed, the scene, the pages
+ * face and the entry that opens the store and mounts it.
+ */
+export function indexHtml(ids) {
+    return `<!doctype html>
+<html lang="en">
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(ids.name)}</title>
+<style>
+  /* The theme is injected by src/main.tsx from the declared brand; this is
+     only the pre-paint ground so the page never flashes white. */
+  html, body { margin: 0; background: #0b0d0b; color: #eaf0ea; }
+</style>
+<div id="root"></div>
+<script type="module" src="/src/main.tsx"></script>
+`;
+}
+/**
+ * SOMEBODY ELSE'S PAGE. The `graview-embed` skill, shipped
+ * as a page rather than as a paragraph — so a project has a place to put an
+ * embed, and so the project's own `pnpm typecheck` covers the embed surface.
+ * Delete both files if the app is never going anywhere but its own address.
+ */
+export function embedHtml(ids) {
+    return `<!doctype html>
+<html lang="en">
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(ids.name)}, on somebody else's page</title>
+<style>
+  /* THE HOST PAGE'S OWN LOOK. Nothing here is ${escapeHtml(ids.name)}'s, and
+     nothing ${escapeHtml(ids.name)} draws may reach out and change it: the
+     embed themes itself inside its own element. */
+  body {
+    margin: 0 auto;
+    max-width: 44rem;
+    padding: 3rem 1.25rem 6rem;
+    background: #fbfaf7;
+    color: #1c1b19;
+    font: 17px/1.7 Georgia, "Times New Roman", serif;
+  }
+  h1 { font-size: 2rem; line-height: 1.15; margin: 0 0 1.2rem; }
+  p { margin: 0 0 1.2rem; }
+  .figure { margin: 1.5rem 0 2rem; height: 520px; }
+</style>
+
+<!-- The HOST page's own landmark. The embed brings a named region of its
+     own and deliberately no <main>: the page it lands on owns that, and two
+     mains is one landmark said twice. -->
+<main>
+  <h1>An ordinary page</h1>
+  <p>
+    Written in its own typeface, on its own paper. The picture below is
+    ${escapeHtml(ids.name)}, mounted into one element of it.
+  </p>
+  <div class="figure" id="here"></div>
+  <p>
+    And the page carries on afterwards, untouched.
+  </p>
+</main>
+
+<script type="module" src="/src/embed.tsx"></script>
+`;
+}
+export function embedTsx(ids) {
+    return `import { mount } from "@graview/embed";
+import { ${ids.appVar}, createStore } from "./domain/app.js";
+import { views } from "./ui/views.js";
+
+/**
+ * ${escapeTemplate(ids.name).toUpperCase()} ON SOMEBODY ELSE'S PAGE.
+ *
+ * The embed brings its own strip, its own theme scoped to the element it is
+ * given, and this app's named places — no Shell, nothing on the host page
+ * touched. Pass \`seats\` once a policy exists and the reader can sit in each
+ * one: the strip, the pages and the acts all narrow together.
+ */
+const store = createStore();
+
+mount(document.getElementById("here")!, {
+  app: ${ids.appVar},
+  store,
+  // The app's own registry, in the app's own schema — no casts.
+  views,
+  scheme: "auto",
+  stop: "#overview=1",
+  label: "${escapeString(ids.name)}",
+});
+`;
+}
+/* ------------------------------------------------------------------- ui */
+export function viewsTsx(ids) {
+    return `import { createViews } from "@graview/react";
+import { registerDefaultViews } from "@graview/primitives";
+import { ${ids.schemaVar} } from "../domain/schema.js";
+
+/**
+ * Nothing custom yet, on purpose. \`registerDefaultViews\` renders every kind
+ * at every fidelity from the declaration alone. Write a view for a kind when
+ * the generic one is genuinely wrong, not on principle — see the framework's
+ * \`apps/todo/src/ui/views.tsx\` for one that earns its place. Give a group
+ * view a title and it is a PLACE, listed by name in the bar:
+ *
+ *   .register("${ids.kind}", { cardinality: "many", fidelity: "full" }, lens.View, { title: "…" })
+ */
+export function views() {
+  return registerDefaultViews(${ids.schemaVar}, createViews(${ids.schemaVar}));
+}
+`;
+}
+export function uiAppTsx(ids) {
+    return `import { EMPTY_VIEW, type ViewState } from "@graview/layout";
+import { GraviewProvider, useGraph, useGraview, type Scheme } from "@graview/react";
+import { AgentSeat, Shell } from "@graview/primitives";
+import { StudioPlace } from "@graview/studio";
+import { templateIntelligence, type ToolCall } from "@graview/tools";
+import { useMemo, useState } from "react";
+import { ${ids.appVar}, createStore, type ${ids.StoreType} } from "../domain/app.js";
+import { ${ids.brandVar} } from "../domain/brand.js";
+import type { ${ids.SchemaType} } from "../domain/schema.js";
+import { views } from "./views.js";
+
+type S = ${ids.SchemaType};
+
+/**
+ * The app opens from ALTITUDE: every kind a district, each saying how many
+ * it holds — or "none yet", which is an invitation rather than a void.
+ */
+export const INITIAL_VIEW: ViewState = { ...EMPTY_VIEW, overview: true };
+
+export interface ${ids.AppComponent}Props {
+  readonly store?: ${ids.StoreType};
+  readonly initialView?: ViewState;
+  readonly syncUrl?: boolean;
+  readonly initialScheme?: Scheme;
+  readonly onSchemeChange?: (scheme: Scheme) => void;
+  /** Whether the store behind this app is remembered in the browser (see main.tsx). */
+  readonly remembers?: boolean;
+}
+
+/**
+ * The whole application. \`Shell\` is the command bar, the scene, the
+ * inspector and the rail, derived; what ${escapeTemplate(ids.name)} adds is a
+ * sentence for when nothing is wrong and a seat for an agent. If this file
+ * grows, ask whether the declaration should have grown instead.
+ */
+export function ${ids.AppComponent}({
+  store,
+  initialView = INITIAL_VIEW,
+  syncUrl = false,
+  initialScheme = "light",
+  onSchemeChange,
+  remembers = false,
+}: ${ids.AppComponent}Props) {
+  const created = useMemo(() => store ?? createStore(), [store]);
+  const registry = useMemo(() => views(), []);
+  const [scheme, setScheme] = useState<Scheme>(initialScheme);
+
+  return (
+    <GraviewProvider
+      store={created}
+      views={registry}
+      initialView={initialView}
+      scheme={scheme}
+      brand={${ids.brandVar}}
+      settings={${ids.appVar}.settings ?? []}
+    >
+      <Shell<S>
+        standing="Everything is in order"
+        /*
+         * THE APP'S OWN DECLARATION, one press away and in place. The
+         * kinds, fields, edges, acts and rules of \`src/domain\` are a graph
+         * here: change one with the ordinary acts, watch the checker judge
+         * it, and apply to get the files to write back. Offered to the seat
+         * that administers where there is one, and to whoever is here where
+         * there is not — which is this project, today.
+         */
+        studio={<StudioPlace app={${ids.appVar}} />}
+        seat={(onCall) => <Starter onCall={onCall} />}
+        remembers={remembers}
+        syncUrl={syncUrl}
+        scheme={scheme}
+        onScheme={(next) => {
+          setScheme(next);
+          onSchemeChange?.(next);
+        }}
+      />
+    </GraviewProvider>
+  );
+}
+
+/**
+ * The seat at zero. An empty graph plus a seat that proposes starter data is
+ * the "describe your domain, get a working app" moment. Every proposal is an
+ * ordinary mutation through the derived tool surface — logged, attributed to
+ * the seat, reviewable, undoable.
+ */
+function Starter({ onCall }: { onCall: (call: ToolCall) => void }) {
+  const { store } = useGraview<S>();
+  const nodes = useGraph();
+  const empty = nodes.length === 0;
+  return (
+    <AgentSeat<S>
+      who="starter"
+      testId="agent-starter"
+      count={empty ? 1 : 0}
+      gate="add-${ids.kind}"
+      label={() => "Add some starter data"}
+      busyLabel="Adding…"
+      idle="There is something here already"
+      onCall={onCall}
+      run={async (agent) => {
+        const starter = templateIntelligence<S>();
+        for (const proposal of await starter.propose(store)) {
+          await agent.run(proposal.mutation, { ...proposal.args });
+        }
+      }}
+    />
+  );
+}
+`;
+}
+export function pagesTsx(ids) {
+    return `import { isCurrent } from "@graview/core";
+import { Begin } from "@graview/primitives";
+import {
+  createPageRegistry,
+  DefaultHomePage,
+  DerivedForm,
+  PageMain,
+  pageStyles,
+  recordFacts,
+  recordPath,
+  Repairs,
+  spatialHref,
+  useStoreTick,
+  type PageComponent,
+  type PageContext,
+} from "@graview/pages";
+import { Link, useParams } from "react-router-dom";
+import { ${ids.schemaVar}, type ${ids.SchemaType} } from "../domain/schema.js";
+
+type S = ${ids.SchemaType};
+
+/**
+ * THE OTHER FACE, IN YOUR OWN WORDS. /pages is an ordinary routed web
+ * application derived from the declaration: a list and a record per kind,
+ * forms from the mutations, a problems page from the rules. Every one of
+ * those can be replaced per kind — or per surface: shell, home, problems —
+ * with a page you write. This is the ${ids.spoken}'s record page; delete it
+ * and the derived page takes over again. Everything it shows still comes
+ * from the same derivations (\`recordFacts\`, \`DerivedForm\`), so a page
+ * you write cannot drift from what the graph says.
+ */
+function ${ids.KindPascal}Page({ context }: { context: PageContext<S> }) {
+  const { store, principal, invariantContext } = context;
+  useStoreTick(store);
+  const id = decodeURIComponent(useParams()["id"] ?? "");
+  const facts = recordFacts(store, id, {
+    ...(principal ? { principal } : {}),
+    ...(invariantContext ? { context: invariantContext } : {}),
+  });
+  const node = store.graph.getNode(id);
+  if (!facts || !node) {
+    return (
+      <PageMain context={context}>
+        <h1 style={pageStyles.h1}>Nothing lives at this address.</h1>
+      </PageMain>
+    );
+  }
+  /*
+   * THE TIES, AS THE DECLARATION READS THEM.
+   *
+   * \`facts.links\` is every edge on this record, both directions, each
+   * carrying the caption the declaration gives THAT end. Asking the graph
+   * for one edge by name here instead — \`out(id, "depends-on")\` — is a
+   * page that stops telling the truth the day the schema grows a second
+   * edge, which is the first thing every project does.
+   */
+  const ties = facts.links;
+  /*
+   * THE ACTS AS THE DERIVATION OFFERS THEM, not as the declaration lists
+   * them. Reaching for a mutation by name gets an act that is always there;
+   * an affordance is an act that can actually be taken RIGHT NOW, and it
+   * carries its candidates — everything not already tied, and never this
+   * record itself. With one ${ids.spoken} in the graph there is nothing to
+   * point at, so there is no form, rather than a heading over a picker with
+   * one wrong answer in it.
+   */
+  const connecting = facts.actions.affordances.filter((affordance) => affordance.ties === true);
+
+  return (
+    <PageMain context={context} data-testid="${ids.kind}-page">
+      <header style={{ display: "grid", gap: 10 }}>
+        <p style={pageStyles.eyebrow}>${ids.ASpoken} in ${escapeTemplate(ids.name)}</p>
+        <h1 style={pageStyles.h1}>{facts.label}</h1>
+        {/*
+          * WHERE IT IS ON THE HORIZON, asked of the declaration's own
+          * lifecycle rather than of a status word written here: rename the
+          * states, or retire by a date, and this still tells the truth.
+          */}
+        <p style={pageStyles.lede}>
+          {isCurrent(store.schema.tryDefinition(node.kind), node) ? "Current." : "In the past: out of the picture, never out of the record."}{" "}
+          {ties.length === 0 ? "Connected to nothing yet." : null}
+        </p>
+        <a href={spatialHref(id)} style={{ ...pageStyles.link, ...pageStyles.quiet }} data-testid="spatial-link">
+          See it in the scene ↗
+        </a>
+      </header>
+      {facts.violations.length > 0 ? (
+        <section style={{ ...pageStyles.rule, display: "grid", gap: 10 }} data-testid="record-violations">
+          {facts.violations.map((violation, index) => (
+            <div key={index} style={{ display: "grid", gap: 8 }}>
+              <p style={{ margin: 0, color: "var(--graview-warn)", fontWeight: 550 }}>{violation.message}</p>
+              {/*
+                * A repair that needs nothing is one press; one that still has
+                * an argument to choose is an ask. \`Repairs\` is the same
+                * component the derived problems page uses, so a page you
+                * write cannot get this wrong on its own.
+                */}
+              <Repairs<S> store={store} repairs={violation.repairs} {...(principal ? { principal } : {})} />
+            </div>
+          ))}
+        </section>
+      ) : null}
+      {/*
+        * THE FACTS, as the derivation reads them — every field that is not
+        * the name, formatted as the declaration says. A page that dropped
+        * them looked finished on the one-kind scaffold, where the only
+        * field is the name, and hid the price of every vehicle a day later.
+        */}
+      {facts.fields.length > 0 ? (
+        <dl style={{ ...pageStyles.rule, margin: 0, display: "grid", gridTemplateColumns: "minmax(0, max-content) minmax(0, 1fr)", gap: "6px 18px" }} data-testid="record-fields">
+          {facts.fields.map((field) => (
+            <div key={field.key} style={{ display: "contents" }}>
+              <dt style={pageStyles.quiet}>{field.label}</dt>
+              <dd style={{ margin: 0, overflowWrap: "anywhere" }}>{field.value}</dd>
+            </div>
+          ))}
+        </dl>
+      ) : null}
+      {ties.length > 0 ? (
+        <section style={{ ...pageStyles.rule, display: "grid", gap: 14 }} data-testid="record-ties">
+          {ties.map((group) => (
+            <div key={\`\${group.edgeKind}|\${group.direction}\`} style={{ display: "grid", gap: 6 }}>
+              {/* The edge's own words for THIS end — its description read
+                  from the end that declared it, its inverse read from the
+                  other. */}
+              <h2 style={pageStyles.h2}>
+                {(group.description ?? group.edgeKind).replace(/^./, (first) => first.toUpperCase())}
+              </h2>
+              {/* Each a link, and two of one name told apart (\`apart\`): a list of words cannot be followed. */}
+              <ul style={{ margin: 0, padding: 0, listStyle: "none", display: "grid", gap: 4 }}>
+                {group.targets.map((target) => (
+                  <li key={target.id}>
+                    <Link to={recordPath(${ids.schemaVar}, target.kind, target.id)} style={pageStyles.link}>
+                      {target.label}
+                      {target.apart ? <span style={pageStyles.quiet}> · {target.apart}</span> : null}
+                    </Link>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))}
+        </section>
+      ) : null}
+      {/*
+        * WITHHELD, NOT HIDDEN. The affordances above are what this seat may
+        * do; an act the policy refuses is in withheld, carrying the policy's
+        * own sentence. Dropping it teaches a person the software is broken —
+        * they watched a colleague do this yesterday and now the control is
+        * gone — so it is drawn struck through with the reason beside it, the
+        * way the derived pages and the scene's strip both draw it.
+        */}
+      {facts.actions.withheld.length > 0 ? (
+        <section style={{ ...pageStyles.rule, display: "grid", gap: 8 }} data-testid="record-withheld">
+          {facts.actions.withheld.map((withheld) => (
+            <p key={withheld.id} style={{ margin: 0, ...pageStyles.quiet }}>
+              <s>{withheld.label}</s> — {withheld.refusal.message}
+            </p>
+          ))}
+        </section>
+      ) : null}
+      {connecting.length > 0 ? (
+        <section style={{ ...pageStyles.rule, display: "grid", gap: 14 }} data-testid="record-actions">
+          {connecting.map((affordance) => {
+            const act = store.allMutations().find((mutation) => mutation.name === affordance.mutation);
+            return act ? (
+              <div key={affordance.id} style={{ display: "grid", gap: 10 }}>
+                {/* The act's own title, and the arguments the derivation
+                    already settled — never a subject name written out here. */}
+                <h2 style={pageStyles.h2}>{affordance.label}</h2>
+                <DerivedForm<S> store={store} mutation={act} prefilled={affordance.args} open={affordance.open} label={affordance.label} {...(principal ? { principal } : {})} />
+              </div>
+            ) : null;
+          })}
+        </section>
+      ) : null}
+    </PageMain>
+  );
+}
+
+/**
+ * THE WAY IN, on the home page, until there is a way past it.
+ *
+ * Every product ships empty once and it is the state its author never sees —
+ * your own graph has had data in it since the first afternoon. \`Begin\` is
+ * derived: it reads the chain your declaration already states (which acts
+ * \`create\` which kinds, and what those acts must be handed first), offers
+ * the ones that can run now, and says what everything else is waiting for.
+ * It stands down on its own once every kind has something in it, which is
+ * why the derived home is what it hands back to.
+ */
+function Home({ context }: { context: PageContext<S> }) {
+  useStoreTick(context.store);
+  return (
+    // The routed face has no provider around it, so the store is handed over.
+    <Begin
+      store={context.store}
+      {...(context.principal ? { principal: context.principal } : {})}
+      // The derived home is a whole page — the gallery, at a page's width,
+      // in its own landmark — and comes back exactly as given.
+      whenFull={<DefaultHomePage context={context} />}
+      // The door alone gets a page's column and landmark around it.
+      frame={(door) => (
+        <PageMain context={context} data-testid="home">
+          {door}
+        </PageMain>
+      )}
+    />
+  );
+}
+
+/** Your pages: every derived page, with the ${ids.spoken}'s record in your own words. */
+export function pages() {
+  return createPageRegistry<S, PageComponent<S>>(${ids.schemaVar})
+    .register("${ids.kind}", "record", ${ids.KindPascal}Page as PageComponent<S>)
+    .surface("home", Home as PageComponent<S>);
+}
+`;
+}
+export function mainTsx(ids) {
+    return `import { PagesApp } from "@graview/pages";
+import { themeCss, type Scheme } from "@graview/primitives";
+import { browserStartsFresh, createBrowserAdapter, forgetFreshParam, openStore } from "@graview/ship/browser";
+import { createRoot } from "react-dom/client";
+import { ${ids.appVar} } from "./domain/app.js";
+import { ${ids.brandVar} } from "./domain/brand.js";
+import { ${ids.AppComponent} } from "./ui/app.js";
+import { pages } from "./ui/pages.js";
+import { views } from "./ui/views.js";
+
+const sheet = new CSSStyleSheet();
+document.adoptedStyleSheets = [sheet];
+
+const STORED = "graview:scheme";
+
+function initialScheme(): Scheme {
+  const asked = new URLSearchParams(window.location.search).get("theme");
+  if (asked === "light" || asked === "dark") return asked;
+  try {
+    const stored = localStorage.getItem(STORED);
+    if (stored === "light" || stored === "dark") return stored;
+  } catch {
+    // A scheme that cannot be remembered still applies for this visit.
+  }
+  return window.matchMedia?.("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+function applyScheme(scheme: Scheme): void {
+  sheet.replaceSync(themeCss(scheme, ${ids.brandVar}));
+  document.documentElement.dataset["graviewScheme"] = scheme;
+  try {
+    localStorage.setItem(STORED, scheme);
+  } catch {
+    // Same again: not being able to remember is not a reason to fail.
+  }
+}
+
+const scheme = initialScheme();
+applyScheme(scheme);
+
+const root = document.getElementById("root");
+if (!root) throw new Error("no #root");
+
+/*
+ * THE APP REMEMBERS. Persistence is the op log; \`openStore\` is the lifecycle
+ * every deployment repeats. Here it is the browser adapter, so an edit
+ * survives a reload, attributed and undoable. \`?fresh=1\` returns to empty;
+ * a driven browser starts fresh unless it asks to remember (\`?remember=1\`),
+ * so a harness specifies the app rather than its own residue.
+ */
+const opened = await openStore({
+  app: ${ids.appVar},
+  adapter: createBrowserAdapter(),
+  fresh: browserStartsFresh(),
+});
+forgetFreshParam();
+
+if (window.location.pathname.startsWith("/pages")) {
+  // The routed, responsive face: same store, same ids, one app.
+  createRoot(root).render(
+    <PagesApp
+      basename="/pages"
+      context={{
+        store: opened.store,
+        brand: ${ids.brandVar},
+        sceneHref: "/",
+        remembers: true,
+        /*
+         * THE SAME PICTURES ON BOTH FACES. Handed the registry the scene
+         * draws from, the pages land on a gallery of them — every kind as
+         * a card until you title a lens, then the lens by its name — with
+         * the map of the kinds and the seat on every route.
+         */
+        views: views(),
+        settings: ${ids.appVar}.settings ?? [],
+      }}
+      // Your own pages over the derived ones: see ui/pages.tsx.
+      registry={pages()}
+    />,
+  );
+} else {
+  createRoot(root).render(
+    <${ids.AppComponent} store={opened.store} remembers syncUrl initialScheme={scheme} onSchemeChange={applyScheme} />,
+  );
+}
+
+// A flag a harness can wait for, rather than a timer and a hope.
+(window as unknown as Record<string, unknown>)["__graviewReady"] = { scheme };
+`;
+}
+//# sourceMappingURL=ui.js.map

package/dist/scaffold/ui.js.map

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

package/dist/schema/define-node.d.ts

@@ -0,0 +1,132 @@
+import type { z } from "zod";
+import type { AnyNodeDefinition, EdgeMap, EmptyEdgeMap, NodeDefinition, NodeDefinitionSpec } from "./types.js";
+/**
+ * The single declaration everything else derives from. Views, agent tool
+ * schemas, drag legality, aggregate contents and accessibility labels all
+ * read this — nothing is sealed, every derived value stays inspectable.
+ */
+export declare function defineNode<const K extends string, F extends z.ZodObject<z.ZodRawShape>, const E extends EdgeMap = EmptyEdgeMap>(kind: K, spec: NodeDefinitionSpec<F, E>): NodeDefinition<K, F, E>;
+/**
+ * Whether a node is CURRENT under its kind's declared lifecycle.
+ *
+ * True when the kind declares no lifecycle — currency is opt-in, and a kind
+ * that never retires anything should not pay for the concept. `today` is
+ * injectable so a test (or a view pinned to a survey date) can ask about a
+ * different day; it defaults to the real one.
+ */
+export declare function isCurrent(definition: AnyNodeDefinition | undefined, node: {
+    id: string;
+    kind: string;
+} & Record<string, unknown>, today?: string): boolean;
+/**
+ * WHAT TELLS TWO SAME-NAMED THINGS APART, among the nodes a person is
+ * choosing from. A single and its album are both "Blue Hour", and every
+ * picker, every ask and the Find strip listed "Blue Hour, Blue Hour": a
+ * choice nobody could make. For each node whose name another in the list
+ * shares, the first fact that differs between them — "single" and "album",
+ * or the dates — else its kind, else its id. Nodes with a name of their
+ * own get nothing.
+ */
+export declare function tellApart(nodes: readonly ({
+    id: string;
+    kind: string;
+} & Record<string, unknown>)[], definitionOf: (kind: string) => AnyNodeDefinition | undefined): Map<string, string>;
+/** Resolves a node's display label, honouring the declaration's override. */
+export declare function labelOf(definition: AnyNodeDefinition | undefined, node: {
+    id: string;
+    kind: string;
+} & Record<string, unknown>): string;
+/**
+ * Prose, shortened to a length, at a WORD BOUNDARY.
+ *
+ * Every app here had `text.slice(0, 60)` in its label function, and every one
+ * of them produced headings like "Hold the banked hour for a night s" — cut
+ * mid-word, with no ellipsis, in the largest type on the page. It is the
+ * obvious thing to write and it is wrong every time, so the framework should
+ * own it rather than leaving each app to discover it.
+ *
+ * A single word longer than the limit is still cut, because the alternative
+ * is a heading that ignores the limit it was given.
+ */
+export declare function summarise(text: string, max?: number): string;
+/** Resolves a node's prose description, used for a11y and tool text. */
+export declare function describeNode(definition: AnyNodeDefinition | undefined, node: {
+    id: string;
+    kind: string;
+} & Record<string, unknown>): string;
+/** One field, as a person sees it. */
+export interface ReadableField {
+    readonly key: string;
+    /** The field name in words, after `display.labels` and humanising. */
+    readonly label: string;
+    /** The value in words, after `display.format` and the built-in defaults. */
+    readonly value: string;
+    /**
+     * The value as it reads WITHOUT its label beside it — on a chip, in a
+     * list line, on a card at summary. A word says what it is ("released");
+     * a number or a yes/no does not, so it carries the label: "Track 8",
+     * "Length 4:27", "Explicit: yes". A song's card read "8 · 4:27 · Yes",
+     * which is three facts and no sentence.
+     */
+    readonly alone: string;
+}
+/** `effectiveFrom` shown to a person is a schema leaking through a surface. */
+export declare function humaniseField(field: string): string;
+/**
+ * A field in words, as the declaration says it: its `display.labels` entry,
+ * else the key spoken. Every sentence that names a field — "Nothing
+ * declared writes the planned time", a tooltip, a refusal — reads it here,
+ * so `plannedAt` never reaches a person from one surface while another says
+ * "Planned at".
+ */
+export declare function fieldWords(definition: {
+    readonly display?: {
+        readonly labels?: Readonly<Record<string, string>>;
+    };
+} | undefined, key: string): string;
+/** "a" or "an", by how the word SOUNDS. */
+export declare function article(word: string): "a" | "an";
+/**
+ * A kind in words, with its article: "an item", "a work order".
+ *
+ * Takes the declared id and speaks it — the hyphen in `work-order` is a
+ * identifier's punctuation, not a word's.
+ */
+export declare function withArticle(word: string): string;
+/**
+ * What one of a kind is called: its declared `noun`, else its id spoken.
+ * Every sentence about ONE of them — "Change the staff member", "a staff
+ * member called …", "Remove the staff member" — reads this, never the id.
+ */
+export declare function nounOf(definition: {
+    readonly noun?: string;
+} | undefined, kind: string): string;
+/**
+ * WHICH of a node's fields a person sees, and HOW each one reads.
+ *
+ * One implementation, because there were two: the record on a page and the
+ * summary on a card each decided this for themselves, and every rule — hide an
+ * ordering key, format minutes as a time, render a boolean as a word, drop a
+ * value the heading already said — had to be written into both and kept in
+ * step by hand. They diverged the day the second one was written, which is how
+ * a summary card ended up showing a list's ordering key as a chip reading "0"
+ * while the page beside it did not.
+ *
+ * `said` is what the surrounding view has already put on screen. A value the
+ * heading already carries is not information twice, it is the same sentence
+ * twice — and where the heading is a SHORTENED form of a field, an exact
+ * comparison never catches it, so the summary's stem is compared too.
+ */
+export declare function readableFields(node: Record<string, unknown>, definition: AnyNodeDefinition | undefined, options?: {
+    readonly limit?: number;
+    readonly said?: readonly (string | undefined)[];
+    /**
+     * A GLANCE drops a value the heading already says as a WORD, not only as
+     * the whole heading: a vehicle's summary is headed "2027 Subaru Forester
+     * Sport", and "Year 2027 · Subaru" under it spent two of its three facts
+     * saying the heading again while the price never appeared. A record's
+     * full facts keep every field — that is where each is changed.
+     */
+    readonly glance?: boolean;
+}): readonly ReadableField[];
+//# sourceMappingURL=define-node.d.ts.map

package/dist/schema/define-node.d.ts.map

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