@ouronet/talos-registry 1.2.0 → 1.3.0

package/README.md

@@ -167,6 +167,24 @@ four-segment pipe-joined string and an account is a glyph string, not a `k:` add
 a placeholder. A preflight-fed parameter is `null` with a note naming the read — the registry
 will not invent a value it has just told you cannot be constructed.
 
+## The tooltip canon
+
+`TOOLTIP-CANON.md` and `tooltipModel()` are the shared rules for rendering a pre-ZBOM tooltip —
+what to show, in what order, and which of it may be prefilled. They are shipped as an
+implementation rather than a document because a document drifts from the code it describes:
+
+```ts
+import { tooltipModel, signatureRows } from "@ouronet/talos-registry";
+const m = tooltipModel("TS01-C1.DPTF|C_Transfer", { id: '"OURO-8Nh-JO8JO4F5"' });
+// m.slots -> EVERY execution parameter, in order, with type, value and flags
+// m.preview -> the INFO_ call with ITS OWN parameter list
+// m.kind -> "ouronet" | "native"   (native renders gold, has no cost section)
+```
+
+Six rules, each there because it was got wrong first — most recently a six-parameter transfer
+whose tooltip showed five arguments, because it was rendering the preview's list under the
+execution's heading. Read the canon before building one.
+
 ### Where a ghost may be used — `ghost.use`
 
 A ghost is not equally safe on every surface, and a single value cannot say so. Entries whose

package/TOOLTIP-CANON.md

@@ -0,0 +1,215 @@
+# The pre-ZBOM tooltip canon
+
+A pre-ZBOM tooltip answers one question: **what will this button actually execute, and what will
+it cost?** Hovering a launcher should tell you before you commit to opening anything.
+
+Two applications render it — OuronetUI and the Codex — and they were converging on it
+independently, each rediscovering the same traps a few weeks apart. **This document is not the
+canon.** `src/tooltip.ts` is. A document drifts from the code it describes and nobody finds out
+until a user sees a wrong number, so the rules are shipped as an implementation:
+
+```ts
+import { tooltipModel, tooltipModels, signatureRows } from "@ouronet/talos-registry";
+
+const m = tooltipModel("TS01-C1.DPTF|C_Transfer", { id: '"OURO-8Nh-JO8JO4F5"' });
+// m.slots  -> every execution parameter, in order, with type, value and flags
+// m.preview -> the INFO_ call, with ITS OWN parameter list
+// m.kind    -> "ouronet" | "native"
+```
+
+This file explains **why** each rule exists. Every one is here because it was got wrong first.
+
+---
+
+## Rule 1 — show every execution parameter
+
+All of them, always, in declared order.
+
+`DPTF|C_Transfer` takes six arguments and its tooltip displayed five, because it was rendering
+the **preview's** list:
+
+```
+execution   (patron executor executee id transfer-amount method)     6
+preview     (patron id sender receiver transfer-amount)              5
+```
+
+Both lists were true. Showing one under a heading that named the other was not. A tooltip that
+lists five rows for a six-parameter function is not a summary — it is a wrong answer, and it
+teaches a call shape that will not work.
+
+`tooltipModel().slots` is always exactly the entrypoint's own parameters. A test asserts this for
+**all 423**, not for the one that was reported.
+
+## Rule 2 — the arguments belong to the execution, the cost belongs to the preview
+
+**410 of the 423 entrypoints have a preview whose parameter list differs from their own.** Only 13
+match. Different names, different order, different arity.
+
+So the two cannot share one numbered list, and the preview's values cannot be labelled with the
+execution's names. That mislabelling was a real defect: it rendered `executor = <the pool id>`,
+`swpair = true`, `toggle = MISSING` for a call that was entirely correct.
+
+Render the execution's arguments as the numbered list. Mention the preview separately — its name,
+its own parameter list, and the cost it returns.
+
+**Bind by NAME, never by position.** Positional merging is silent: both values are strings, so an
+executor's account lands in a token-id slot, type-checks, and prices a different question.
+`tooltipModel(key, values)` merges by name and cannot do otherwise.
+
+## Rule 3 — types go on their own row
+
+```
+(patron executor executee id transfer-amount method)
+(string string string   string decimal         bool)
+```
+
+not
+
+```
+(patron:string executor:string executee:string id:string transfer-amount:decimal method:bool)
+```
+
+The inline form roughly doubles the width of the widest line in the panel, and the panel is
+already the widest thing on screen when it opens. A parallel row costs one line.
+
+`signatureRows(m)` returns `{ names, types }` as equal-length arrays for exactly this.
+
+## Rule 4 — native is not Ouronet, and the difference is narrower than it looks
+
+A `coin.*` call is StoaChain's own root-namespace contract. It is **not** in this registry and
+never will be: the registry is generated from `ouronet-ns`.
+
+What is actually different:
+
+| | Ouronet | native |
+|---|---|---|
+| INFO_ preview | yes | **no** — nothing prices a `coin` call |
+| IGNIS | collected | **none** |
+| accounts | Ouronet glyph strings | **Kadena-shaped** (`k:` `c:` `u:` `w:`) |
+| gas sponsorship | gas station pays | **gas station pays** — the same |
+
+**That last row is the one to get right.** An earlier version of this claimed a native call was
+not sponsored and that the signing account paid its own STOA gas. Both false: every native modal
+carries `GAS_PAYER` on the gas-station key beside its own capability, and says so in its own
+header comment. The claim had been *inferred* from "this is not an Ouronet operation", which says
+nothing about who pays the host chain — and it was wrong in the direction that matters, telling a
+user they were about to spend when they were not.
+
+**Render native with a gold perimeter.** The gold is semantic, not decorative: it means *nothing
+here prices this call*. And say what is missing rather than leaving the cost panel empty — an
+empty panel reads as "the price failed to load".
+
+Suggested footer, which is what OuronetUI ships:
+
+```
+no IGNIS — this is not an Ouronet operation
+a StoaChain `coin` call, so nothing prices it. Gas is still sponsored.
+```
+
+Signatures for the native calls are in `NATIVE_SIGNATURES`, transcribed from the deployed
+contract with line numbers. Use them rather than typing your own.
+
+## Rule 5 — a ghost is not data
+
+Every parameter has a worked example. The shapes are real — read from mainnet — so you can see
+that a swpair is a four-segment pipe-joined string and an account is a glyph string, not a `k:`
+address. **They are not submittable**, and three cases need distinguishing:
+
+- **`isPlaceholder`** — the generic `"example"`. 225 slots across 147 entrypoints, every one an
+  entity id for something that **does not exist on chain** (`fvt-id`, `pool-id`, `score-id`,
+  `anchor-id`). Mainnet holds zero anchors and zero scores today. A plausible fake id would return
+  a confident price for something nobody owns, which is worse than an obvious gap. **Render it so
+  it reads as a placeholder** — grey it, italicise it, anything but plain.
+- **`isPreflightFed`** — the argument is the *output of a read*, not user input. The registry
+  refuses to invent one and so must you. `execution.preflight` names the read.
+- **`prefillable: false`** — a guard. See rule 6.
+
+**Do not fire the preview read when any argument is a placeholder.** The answer is a foregone
+refusal, and a read per hover is latency the user pays for a known-no. `m.shouldRead` is already
+false in that case.
+
+## Rule 6 — a guard may be shown and must not be prefilled
+
+Six entrypoints take a `guard`, and five are account operations:
+
+```
+DALOS|C_DeploySmartAccount · DALOS|C_DeployStandardAccount · DALOS|C_RotateGovernor
+DALOS|C_RotateGuard · CODEX|C_RotateCodexGuard · AQP-DSA|C_SetOracleAuth
+```
+
+A ghost carries two use tags, both defaulting true, emitted only where something is restricted:
+
+```jsonc
+"use": { "new-guard": { "zbom": false, "display": "(read-keyset \"ks\")" } }
+```
+
+- **`zbom: false`** — never prefill it into an input that can reach a signed transaction. You do
+  not hand someone a keyset and ask them to sign under it.
+- **`display`** — render *this* instead of the value. The submittable form and the readable form
+  differ: `{"readKeyset": "ks"}` is a transaction-data key NAME, and `(read-keyset "ks")` is what
+  a caller actually writes.
+
+A value that is **correct to show and wrong to submit** is precisely what one tag cannot express,
+which is why there are two. `tooltipModel` applies both for you.
+
+---
+
+## Placement and behaviour
+
+Not expressible in the model, so they are stated here and they are not optional.
+
+**On the LAUNCHER, never on the ZBOM's execute button.** Owner ruling. Inside a ZBOM the
+information is already on the page — the input zone lists every parameter with its declared type,
+the INFO panel shows the cost — and a tooltip there draws *over* the modal it annotates. The
+tooltip exists to tell you what a button will do **before** you commit to opening it.
+
+**Anchor the edge NEAREST the button.** Placed above, pin the bottom and grow upward; placed
+below, pin the top and grow down. Either way the edge beside the button never moves. Pinning the
+top in both orientations — from an assumed height — makes every content change move the bottom
+edge, so a cycling panel grows and shrinks *away* from the button, which is the direction nobody
+is looking.
+
+**Cycle at 10 seconds** when a button fronts several executions. One window, a depletion bar, a
+dot per variant. The transaction toaster's ~3s is the wrong model to copy: a toast is glanced at,
+this panel is read — an entrypoint, a parameter list, six arguments and a live cost. Restart at
+the first variant on every hover; a panel resuming mid-cycle describes an operation you did not
+just point at. Cycle in the order the ZBOM presents, so the first thing hovered is the first thing
+met.
+
+**Use pointer events.** `onMouseLeave` fires when the cursor crosses onto a child in some engines;
+`pointerleave` does not.
+
+**A flickering tooltip is usually a REMOUNT.** If a button component is declared *inside* another
+component's body, every render creates a new component type and React unmounts the whole subtree,
+destroying the open state. Hoist to module scope.
+
+**Key the preview effect on the rendered CALL STRING**, not on a values object. An inline literal
+gives a new object identity every render; keying on it re-fires the read, which sets state, which
+re-renders — forever.
+
+**Fail open.** An unknown key renders the children alone. A tooltip is an affordance; taking a
+page down because a hint has no data is a worse bug than the missing hint.
+
+**Elide long values in the middle, keeping head AND tail.** An Ouronet account is 162 glyphs;
+three in one call makes a tooltip taller than the card it annotates. `"OURO-8Nh…JO4F5"` identifies
+a value where a truncated prefix does not. Keep the quotes *outside* the elision — a reader has to
+be able to tell a Pact string from a bare decimal — and put the full value on `title`.
+
+## Enforce it, do not remember it
+
+The rule is about a **class**: every button that opens a ZBOM. Classes are where hand-checking
+fails. OuronetUI's guard walks every page, finds every ZBOM-opening launcher and fails on a naked
+one — it was written after the Define buttons were missed once, and it had to be widened after
+three whole toolbars shipped bare while it read a single file and claimed the class.
+
+Two things such a guard must get right: model **both** coverage forms (a textual wrap, or an
+`entrypoint=` on a component that wraps internally), and exclude `onClose` handlers, which close a
+ZBOM rather than open one.
+
+---
+
+## Sources
+
+- `src/tooltip.ts` — the canon itself; `tests/tooltip.test.ts` enforces all six rules
+- 410-of-423 preview divergence, 225 placeholder slots: recomputed from the bundled registry
+- The sponsorship correction: owner, 2026-09-27

package/dist/index.d.ts

@@ -16,4 +16,6 @@ export type { CallPlan } from "./plan.js";
 export { parseCapability, parseCapabilities, capabilityRecipe } from "./caps.js";
 export type { ParsedCapability, CapabilityRecipe } from "./caps.js";
 export { formatForType, formatDecimal, formatInteger, formatString, formatBool } from "./format.js";
+export { tooltipModel, tooltipModels, signatureRows, isNativeKey, isPlaceholder, PLACEHOLDER, NATIVE_SIGNATURES } from "./tooltip.js";
+export type { TooltipModel, TooltipSlot, TooltipPreview } from "./tooltip.js";
 export type * from "./types.js";

package/dist/index.js

@@ -13,3 +13,6 @@ export { buildCall, buildPreviewCall, buildGhostCall } from "./build.js";
 export { planCall, explainCall } from "./plan.js";
 export { parseCapability, parseCapabilities, capabilityRecipe } from "./caps.js";
 export { formatForType, formatDecimal, formatInteger, formatString, formatBool } from "./format.js";
+// THE TOOLTIP CANON. Shared implementation rather than a shared document -- see TOOLTIP-CANON.md
+// for why each rule exists, and `tooltip.ts` for the rules themselves.
+export { tooltipModel, tooltipModels, signatureRows, isNativeKey, isPlaceholder, PLACEHOLDER, NATIVE_SIGNATURES } from "./tooltip.js";

package/dist/tooltip.d.ts

@@ -0,0 +1,91 @@
+/** One parameter of the execution, with everything a renderer needs about it. */
+export interface TooltipSlot {
+    /** 1-based, so a renderer never has to decide whether to add one. */
+    index: number;
+    name: string;
+    /** the Pact type as DECLARED. Rendered on its own row -- rule 3. */
+    type: string;
+    /** the rendered Pact literal, or the `display` override where one exists. */
+    value: string;
+    /** the generic "example" ghost: an entity that does not exist on chain. Render it as such. */
+    isPlaceholder: boolean;
+    /** the output of a preflight read. There is no value and none may be invented. */
+    isPreflightFed: boolean;
+    /** false = never prefill into an input that can reach a signed transaction (guards). */
+    prefillable: boolean;
+    /** the registry's own note about this argument, when it has one. */
+    note?: string;
+}
+export interface TooltipPreview {
+    /** fully qualified INFO_ reader. */
+    name: string;
+    /** ITS parameter names, which are usually not the execution's. */
+    params: string[];
+    /** the rendered call, ready to `/local`. */
+    call: string;
+}
+export interface TooltipModel {
+    /** `native` renders with a gold perimeter and no cost section -- rule 4. */
+    kind: "ouronet" | "native";
+    /** fully qualified execution, as it would be typed in a transaction. */
+    exec: string;
+    /** EVERY execution parameter, in declared order -- rule 1. */
+    slots: TooltipSlot[];
+    /** absent for native calls: nothing on StoaChain's `coin` contract prices a call. */
+    preview?: TooltipPreview;
+    /**
+     * Whether a renderer should fire the preview read.
+     *
+     * False when any argument is a placeholder -- the read would refuse, and a refusal per hover is
+     * latency the user pays for a foregone conclusion. Rule 5.
+     */
+    shouldRead: boolean;
+    /** things a renderer may want to surface. Never thrown; a tooltip must not take a page down. */
+    warnings: string[];
+}
+/** The registry's generic placeholder: an entity id for something that does not exist on chain. */
+export declare const PLACEHOLDER = "\"example\"";
+export declare const isPlaceholder: (rendered: string) => boolean;
+/** A `coin.*` key is StoaChain's root-namespace contract -- outside this registry by design. */
+export declare const isNativeKey: (key: string) => boolean;
+/**
+ * STOA-native specs, which the generated registry does not and will not describe.
+ *
+ * They live HERE rather than in each consumer so that both applications render the same
+ * signatures. Transcribed from the deployed contract with its line numbers; `tooltip.test.ts`
+ * asserts internal consistency and the Pact repo's own test re-reads the source.
+ *
+ *   source: 0_Stoa/coin-contract/coin-live.pact
+ */
+export declare const NATIVE_SIGNATURES: Readonly<Record<string, ReadonlyArray<[string, string]>>>;
+/**
+ * Everything a renderer needs for one entrypoint.
+ *
+ * `values` overrides ghosts BY PARAMETER NAME. Never positionally: 410 of 423 previews declare a
+ * different list from their entrypoint, and positional merging is how an executor's account ends
+ * up in a token-id slot -- silently, because both are strings.
+ *
+ * Throws only on an unknown key, which is a programming error. Everything else degrades: an
+ * unresolvable argument becomes a visible placeholder rather than an exception, because a tooltip
+ * must never take down the page it annotates.
+ */
+export declare function tooltipModel(key: string, values?: Readonly<Record<string, string>>): TooltipModel;
+/**
+ * Models for a button that fronts a CHOICE of executions, in the order the ZBOM presents them.
+ *
+ * Unknown keys are DROPPED rather than throwing: a button offering three executions should not
+ * lose its tooltip because one is stale. The absence is reported in `warnings` of the survivors'
+ * caller instead -- and if nothing survives, the caller renders no tooltip, which is the correct
+ * outcome and not a crash.
+ */
+export declare function tooltipModels(keys: readonly string[], values?: Readonly<Record<string, string>>): TooltipModel[];
+/**
+ * The type row -- rule 3.
+ *
+ * Returned parallel to the names so a renderer can print two aligned lines rather than
+ * `name:type` pairs, which double the width of the widest line in the panel.
+ */
+export declare function signatureRows(m: TooltipModel): {
+    names: string[];
+    types: string[];
+};

package/dist/tooltip.js

@@ -0,0 +1,226 @@
+/**
+ * THE TOOLTIP CANON, as code.
+ *
+ * A pre-ZBOM tooltip answers one question: *what will this button actually execute, and what will
+ * it cost?* Two applications render it -- OuronetUI and the Codex -- and they had been converging
+ * on it independently, each rediscovering the same traps a few weeks apart. This module exists so
+ * the rules are a SHARED IMPLEMENTATION rather than a shared document, because a document drifts
+ * from the code it describes and nobody finds out until a user sees a wrong number.
+ *
+ * `TOOLTIP-CANON.md` beside this file explains WHY each rule exists. This file is the rule.
+ *
+ * ── THE FIVE RULES ────────────────────────────────────────────────────────────────────────────
+ *
+ * 1. SHOW EVERY EXECUTION PARAMETER. All of them, always, in declared order. A tooltip that lists
+ *    five rows for a six-parameter function is not a summary, it is a wrong answer -- and it is
+ *    how `DPTF|C_Transfer` came to display five arguments for a six-argument call.
+ *
+ * 2. THE ARGUMENTS BELONG TO THE EXECUTION, the cost belongs to the preview. 410 of 423
+ *    entrypoints have a preview whose parameter list DIFFERS from their own, so the two cannot
+ *    share one numbered list. Render the execution's; mention the preview's separately.
+ *
+ * 3. TYPES GO ON THEIR OWN ROW. `patron:string executor:string ...` doubles the width of the
+ *    widest line in the panel. A parallel row under the names costs one line and reads better.
+ *
+ * 4. NATIVE IS NOT OURONET, and the difference is narrow. A `coin.*` call has no INFO_ preview
+ *    and collects no IGNIS. Gas IS still sponsored -- claiming otherwise tells a user they are
+ *    about to spend when they are not. Render native with a gold perimeter so the two are never
+ *    confused, and say what is actually different rather than inventing a difference.
+ *
+ * 5. A GHOST IS NOT DATA. An unresolved argument must LOOK unresolved, and a tooltip whose
+ *    arguments are placeholders must not fire the preview read at all: the answer is a foregone
+ *    refusal and the latency is paid by the user for nothing.
+ */
+import { getEntrypoint, getPreview, tryGetEntrypoint, registry } from "./registry.js";
+import { formatForType } from "./format.js";
+/** The registry's generic placeholder: an entity id for something that does not exist on chain. */
+export const PLACEHOLDER = '"example"';
+export const isPlaceholder = (rendered) => rendered === PLACEHOLDER;
+/** A `coin.*` key is StoaChain's root-namespace contract -- outside this registry by design. */
+export const isNativeKey = (key) => key.startsWith("coin.");
+/**
+ * STOA-native specs, which the generated registry does not and will not describe.
+ *
+ * They live HERE rather than in each consumer so that both applications render the same
+ * signatures. Transcribed from the deployed contract with its line numbers; `tooltip.test.ts`
+ * asserts internal consistency and the Pact repo's own test re-reads the source.
+ *
+ *   source: 0_Stoa/coin-contract/coin-live.pact
+ */
+export const NATIVE_SIGNATURES = {
+    // [name, type] pairs, in declared order.
+    "coin.C_Transfer": [["sender", "string"], ["receiver", "string"], ["amount", "decimal"]], // :583
+    "coin.C_Transmit": [["sender", "string"], ["receiver", "string"], ["amount", "decimal"]], // :593
+    "coin.C_TransferAnew": [["sender", "string"], ["receiver", "string"], ["receiver-guard", "guard"], ["amount", "decimal"]], // :586
+    "coin.C_TransmitAnew": [["sender", "string"], ["receiver", "string"], ["receiver-guard", "guard"], ["amount", "decimal"]], // :599
+    "coin.C_UR|Transfer": [["sender", "string"], ["receiver", "string"], ["amount", "decimal"]], // :1075
+    "coin.C_UR|Transmit": [["sender", "string"], ["receiver", "string"], ["amount", "decimal"]], // :1085
+    "coin.C_URV|Stake": [["account", "string"], ["urstoa-amount", "decimal"]], // :1407
+    "coin.C_URV|Unstake": [["account", "string"], ["urstoa-amount", "decimal"]], // :1439
+    "coin.C_URV|Collect": [["account", "string"]], // :1467
+};
+/** Kadena-shaped, NOT an Ouronet glyph account -- a `coin` call takes k:/c:/u:/w:. */
+const NATIVE_GHOST = {
+    string: '"k:1ac0d8b0a4f6e2c9d3b5a7e1f4c6089d2b3e5a7c9f1d3b5e7a9c1f3d5b7e9a1c"',
+    decimal: "1.0",
+    integer: "1",
+    bool: "false",
+    guard: '(read-keyset "ks")',
+};
+function nativeModel(key, values) {
+    // Callers reach this only through `tooltipModel`, which has already rejected an unknown key.
+    // Asserted rather than assumed: a non-null assertion here would make a future direct caller
+    // fail with a property access on undefined instead of a sentence naming the problem.
+    const sig = NATIVE_SIGNATURES[key];
+    if (!sig)
+        throw new Error(`nativeModel: no signature for "${key}"`);
+    return {
+        kind: "native",
+        exec: key,
+        slots: sig.map(([name, type], i) => ({
+            index: i + 1,
+            name,
+            type,
+            value: values[name] ?? NATIVE_GHOST[type] ?? PLACEHOLDER,
+            isPlaceholder: values[name] === undefined && NATIVE_GHOST[type] === undefined,
+            isPreflightFed: false,
+            // A guard is never prefillable, native or not. Same rule, same reason.
+            prefillable: type !== "guard",
+        })),
+        // No preview, deliberately. Rule 4: nothing on `coin` prices a call, so there is no cost to
+        // show and a renderer must say that rather than leaving an empty panel that reads as a
+        // failed load.
+        shouldRead: false,
+        warnings: [],
+    };
+}
+/**
+ * Everything a renderer needs for one entrypoint.
+ *
+ * `values` overrides ghosts BY PARAMETER NAME. Never positionally: 410 of 423 previews declare a
+ * different list from their entrypoint, and positional merging is how an executor's account ends
+ * up in a token-id slot -- silently, because both are strings.
+ *
+ * Throws only on an unknown key, which is a programming error. Everything else degrades: an
+ * unresolvable argument becomes a visible placeholder rather than an exception, because a tooltip
+ * must never take down the page it annotates.
+ */
+export function tooltipModel(key, values = {}) {
+    if (isNativeKey(key)) {
+        if (!NATIVE_SIGNATURES[key])
+            throw new Error(`tooltipModel: unknown native key "${key}". ` +
+                `Known: ${Object.keys(NATIVE_SIGNATURES).join(", ")}`);
+        return nativeModel(key, values);
+    }
+    const ep = getEntrypoint(key); // throws, and names near matches, on a stale key
+    const warnings = [];
+    const use = ep.ghost.use ?? {};
+    // RULE 1: every parameter, in declared order. Not the preview's list, not a subset.
+    const slots = ep.params.map((p, i) => {
+        const supplied = values[p.name];
+        const raw = ep.ghost.args[p.name];
+        const u = use[p.name];
+        let value;
+        let isPlaceholder = false;
+        const isPreflightFed = raw === null;
+        if (supplied !== undefined) {
+            value = supplied;
+        }
+        else if (u?.display !== undefined) {
+            // The submittable form and the readable form differ -- a guard is `(read-keyset "ks")` to
+            // a reader and a data-key name to the transaction builder.
+            value = u.display;
+        }
+        else if (isPreflightFed) {
+            value = "<from preflight>";
+        }
+        else if (raw === undefined) {
+            value = PLACEHOLDER;
+            isPlaceholder = true;
+            warnings.push(`no ghost for ${p.name}:${p.type}`);
+        }
+        else {
+            try {
+                value = formatForType(raw, p.type);
+            }
+            catch {
+                value = PLACEHOLDER;
+                isPlaceholder = true;
+                warnings.push(`ghost for ${p.name} does not fit ${p.type}`);
+            }
+            if (isPlaceholder || value === PLACEHOLDER)
+                isPlaceholder = true;
+        }
+        return {
+            index: i + 1,
+            name: p.name,
+            type: p.type,
+            value,
+            isPlaceholder,
+            isPreflightFed,
+            prefillable: u?.zbom !== false,
+            note: ep.ghost.notes?.[p.name],
+        };
+    });
+    // RULE 2: the preview is priced with ITS OWN parameter list, which is usually not this one.
+    let preview;
+    const pvKey = ep.preview;
+    const pv = pvKey ? getPreview(pvKey) : undefined;
+    if (pvKey && pv) {
+        const args = pv.params.map((p) => {
+            const supplied = values[p.name];
+            if (supplied !== undefined)
+                return supplied;
+            const raw = ep.ghost.args[p.name];
+            if (raw === undefined || raw === null)
+                return PLACEHOLDER;
+            try {
+                return formatForType(raw, p.type);
+            }
+            catch {
+                return PLACEHOLDER;
+            }
+        });
+        preview = {
+            name: `${registry.namespace}.${pvKey}`,
+            params: pv.params.map((p) => p.name),
+            call: `(${registry.namespace}.${pvKey} ${args.join(" ")})`,
+        };
+        if (args.some(isPlaceholder))
+            warnings.push("preview has placeholder arguments; the read would refuse");
+    }
+    else if (pvKey) {
+        warnings.push(`preview ${pvKey} is named but not in the registry`);
+    }
+    return {
+        kind: "ouronet",
+        exec: `${registry.namespace}.${key}`,
+        slots,
+        preview,
+        // RULE 5: do not fire a read whose answer is a foregone refusal.
+        shouldRead: preview !== undefined && !preview.call.includes(PLACEHOLDER),
+        warnings,
+    };
+}
+/**
+ * Models for a button that fronts a CHOICE of executions, in the order the ZBOM presents them.
+ *
+ * Unknown keys are DROPPED rather than throwing: a button offering three executions should not
+ * lose its tooltip because one is stale. The absence is reported in `warnings` of the survivors'
+ * caller instead -- and if nothing survives, the caller renders no tooltip, which is the correct
+ * outcome and not a crash.
+ */
+export function tooltipModels(keys, values = {}) {
+    return keys
+        .filter((k) => isNativeKey(k) ? Boolean(NATIVE_SIGNATURES[k]) : Boolean(tryGetEntrypoint(k)))
+        .map((k) => tooltipModel(k, values));
+}
+/**
+ * The type row -- rule 3.
+ *
+ * Returned parallel to the names so a renderer can print two aligned lines rather than
+ * `name:type` pairs, which double the width of the widest line in the panel.
+ */
+export function signatureRows(m) {
+    return { names: m.slots.map((s) => s.name), types: m.slots.map((s) => s.type) };
+}

package/dist/types.d.ts

@@ -104,11 +104,26 @@ export interface ExternalCaps {
     attachTo: string;
     note: string;
 }
+/** Where a single ghost value may be used. Absent field = permitted. */
+export interface GhostUse {
+    /** false = MUST NOT be prefilled into an input that can reach a signed transaction. */
+    zbom?: boolean;
+    /** false = must not be rendered at all. */
+    tooltip?: boolean;
+    /** render this string instead of the value (the submittable and readable forms differ). */
+    display?: string;
+}
 export interface Ghost {
     /** example arguments by parameter name. `null` means "obtain from the preflight". */
     args: Record<string, unknown>;
     source: string;
     notes?: Record<string, string>;
+    /**
+     * Per-parameter surface restrictions. Present ONLY for parameters that have one -- 6 of 423
+     * entrypoints today, all guard-taking. An absent parameter is unrestricted.
+     */
+    use?: Record<string, GhostUse>;
+    useNote?: string;
     unresolved?: string[];
     unresolvedNote?: string;
     warning: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouronet/talos-registry",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "The Ouronet callable surface, generated from the deployed contracts. Supply values; never type a function name.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,8 @@
   "files": [
     "dist",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "TOOLTIP-CANON.md"
   ],
   "scripts": {
     "sync": "node scripts/sync-registry.mjs",