@ouronet/talos-registry 2.0.0 → 2.1.0

package/README.md

@@ -178,10 +178,12 @@ 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" | "stoa" | "kadena"   (only ouronet has a cost section)
+// m.kind       -> "ouronet" | "stoa" | "kadena"  (only ouronet has a cost section)
+// m.chainColor -> the CANONICAL border colour for that chain
+// m.consumer   -> who is rendering, for the caller zone
 ```
 
-Seven rules, each there because it was got wrong first — most recently a six-parameter transfer
+Eight 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.
 

package/TOOLTIP-CANON.md

@@ -126,21 +126,61 @@ header comment. The claim had been *inferred* from "this is not an Ouronet opera
 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.
 
-**Make the two visually distinct — the palette is yours.** The distinction is mandatory because
-the two differ in what they cost and what can be previewed; the specific colour is presentation,
-and this package does not get a vote on your design language. A rule that mandates a palette in
-someone else's application is a rule that gets ignored, and an ignored rule weakens the ones that
-matter.
+### The palette is canon — `CHAIN_PALETTE`
+
+| chain | colour | |
+|---|---|---|
+| `ouronet` | `#3b82f6` | **blue** |
+| `stoa` | `#ceac5f` | **gold** |
+| `kadena` | `#22c55e` | **green** |
+
+**This reverses the 1.4.0 position**, which said the palette was each app's business. The
+reasoning then — that a package should not dictate colours inside someone else's design language —
+was right about *decoration* and wrong about *this*. The colour encodes **which chain your money
+is on**. Two apps teaching different meanings for the same colour is worse than neither using
+colour at all, because a user believes whichever they learned first, and these two apps share
+users.
+
+`m.chainColor` and `m.chainLabel` are on the model so a renderer cannot quietly pick a different
+one, and a test asserts every chain has both — if `Chain` ever gains a member without a colour,
+that fails rather than rendering `undefined`, which CSS ignores and which therefore looks like
+"no border rule" instead of a bug.
+
+Colours were taken from what was already in use rather than invented: gold is OuronetUI's STOA
+accent, blue its established `#3b82f6`, green its success green — unused on any tooltip surface
+and therefore free to carry this meaning.
 
-In practice:
+**Make the distinction run in every direction.** We coloured `stoa` gold and left `ouronet` on the
+panel's ordinary grey, so it only existed one way: a reader who never hovered a native button
+learned no rule at all, and gold read as "something is odd about this one" rather than as a
+category. Every kind gets a colour *and* a label.
 
-| | `stoa` | `ouronet` | `kadena` |
-|---|---|---|---|
-| OuronetUI | gold `#ceac5f` | blue `#3b82f6` | *(not surfaced)* |
-| Codex | *its own* | violet | **green** |
+And **say what is missing** rather than leaving the cost panel empty — an empty panel reads as
+"the price failed to load".
+
+## Rule 4b — say who is rendering
+
+Two applications draw this tooltip, and a Codex panel can open over an OuronetUI page. That is
+exactly the case where "whose tooltip is this" is hardest to infer from chrome and most useful to
+state.
+
+**Carry a caller zone naming the consumer.** One line, its own accent:
+
+```ts
+tooltipModel(key, values, CONSUMERS.Codex)      // m.consumer -> { name, accent }
+```
+
+| consumer | accent | |
+|---|---|---|
+| `OuronetUI` | `#d2d3d4` | neutral |
+| `Codex` | `#8b5cf6` | **violet** |
 
-Whatever you choose, make it carry meaning rather than decoration, and **say what is missing**
-rather than leaving the cost panel empty — an empty panel reads as "the price failed to load".
+**Two axes, deliberately.** The border says *what you are looking at*; the caller zone says *who
+is showing it to you*. A consumer accent is therefore never a chain colour, and a test asserts the
+two sets do not intersect — the moment they do, the two meanings merge and both become unreadable.
+
+`name` matches the `consumerName` each app already uses for its codex settings, so the workspace
+has one spelling of "OuronetUI" rather than two.
 
 Suggested footer, which is what OuronetUI ships:
 
@@ -152,11 +192,6 @@ a StoaChain `coin` call, so nothing prices it. Gas is still sponsored.
 Signatures are in `STOA_SIGNATURES` and `KADENA_SIGNATURES`, transcribed from the deployed
 contracts with line numbers. Use them rather than typing your own.
 
-**Make the distinction run in every direction.** We coloured `stoa` gold and left `ouronet` on the
-panel's ordinary grey — so the distinction existed one way only, and a reader who never hovered a
-native button learned no rule at all. Gold then reads as "something is odd about this one" rather
-than as a category. Give every kind a colour and a label, not just the exceptional ones.
-
 ## Rule 5 — a ghost is not data
 
 Every parameter has a worked example. The shapes are real — read from mainnet — so you can see

package/dist/index.d.ts

@@ -16,6 +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, chainOf, isOffRegistryKey, isNativeKey, isPlaceholder, PLACEHOLDER, STOA_SIGNATURES, KADENA_SIGNATURES, NATIVE_SIGNATURES } from "./tooltip.js";
-export type { TooltipModel, TooltipSlot, TooltipPreview } from "./tooltip.js";
+export { tooltipModel, tooltipModels, signatureRows, chainOf, isOffRegistryKey, isNativeKey, isPlaceholder, PLACEHOLDER, CHAIN_PALETTE, CHAIN_LABEL, CONSUMERS, STOA_SIGNATURES, KADENA_SIGNATURES, NATIVE_SIGNATURES } from "./tooltip.js";
+export type { TooltipModel, TooltipSlot, TooltipPreview, Chain, ConsumerIdentity } from "./tooltip.js";
 export type * from "./types.js";

package/dist/index.js

@@ -15,4 +15,4 @@ 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, chainOf, isOffRegistryKey, isNativeKey, isPlaceholder, PLACEHOLDER, STOA_SIGNATURES, KADENA_SIGNATURES, NATIVE_SIGNATURES } from "./tooltip.js";
+export { tooltipModel, tooltipModels, signatureRows, chainOf, isOffRegistryKey, isNativeKey, isPlaceholder, PLACEHOLDER, CHAIN_PALETTE, CHAIN_LABEL, CONSUMERS, STOA_SIGNATURES, KADENA_SIGNATURES, NATIVE_SIGNATURES } from "./tooltip.js";

package/dist/tooltip.d.ts

@@ -1,3 +1,41 @@
+/** The three worlds a tooltip can describe. See rule 4. */
+export type Chain = "ouronet" | "stoa" | "kadena";
+/**
+ * The canonical border colour per chain. USE THESE.
+ *
+ * Not styling: the colour tells a user which chain their money is on, and that vocabulary is
+ * shared between the applications that render it. Two apps teaching different meanings for the
+ * same colour is worse than neither using colour at all, because the user believes the first one
+ * they learned.
+ *
+ *   ouronet  blue    the ouronet-ns surface -- priced, IGNIS, sponsored
+ *   stoa     gold    StoaChain's own coin -- unpriced, no IGNIS, still sponsored
+ *   kadena   green   a DIFFERENT CHAIN -- its own gas, its own balances
+ *
+ * Chosen from what was already in use rather than invented: gold is OuronetUI's STOA accent and
+ * blue its established `#3b82f6`; green is the app's existing success green, which is unused on
+ * any other tooltip surface and therefore free to carry this meaning.
+ */
+export declare const CHAIN_PALETTE: Readonly<Record<Chain, string>>;
+/** Human label for the chain, for the border-adjacent marker. */
+export declare const CHAIN_LABEL: Readonly<Record<Chain, string>>;
+/**
+ * Who is drawing the tooltip -- rule 4b.
+ *
+ * Two applications render this, and a Codex panel can open over an OuronetUI page, which is
+ * exactly the case where "whose tooltip is this" is hardest to infer from chrome and most useful
+ * to state. The accent is the CONSUMER's identity and is deliberately a different axis from
+ * `CHAIN_PALETTE`: one says what you are looking at, the other says who is showing it to you.
+ *
+ * `name` matches the `consumerName` key each app already uses for its codex settings, so there is
+ * one spelling of "OuronetUI" across the workspace rather than two.
+ */
+export interface ConsumerIdentity {
+    name: string;
+    /** the app's own accent for the caller zone. NOT a chain colour. */
+    accent: string;
+}
+export declare const CONSUMERS: Readonly<Record<"OuronetUI" | "Codex", ConsumerIdentity>>;
 /** 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. */
@@ -33,11 +71,8 @@ export interface TooltipModel {
      *   kadena   Kadena mainnet's `coin`. A DIFFERENT CHAIN -- different gas, different accounts,
      *            and nothing about Ouronet applies to it.
      *
-     * A renderer MUST make these visually distinct, because they differ in what they cost and what
-     * can be previewed. It is NOT told how: OuronetUI uses gold/blue, the Codex violet for Ouronet
-     * and green for Kadena, and all are conformant. Mandating a palette in a package consumed by
-     * applications with their own design languages is a rule that gets ignored, and an ignored rule
-     * weakens the ones that matter.
+     * Each has a canonical colour in `CHAIN_PALETTE`, and a renderer should use it: the colour
+     * encodes which chain the user's money is on, which is shared vocabulary rather than styling.
      *
      * RENAMED from `"native"` in 2.0.0. With only two worlds "native" was unambiguous; with three
      * it silently invited the question "native to WHAT" -- and both candidate answers are a
@@ -57,6 +92,12 @@ export interface TooltipModel {
      * latency the user pays for a foregone conclusion. Rule 5.
      */
     shouldRead: boolean;
+    /** the canonical border colour for `kind`. Convenience -- identical to CHAIN_PALETTE[kind]. */
+    chainColor: string;
+    /** the label to print beside it: OURONET / STOA NATIVE / KADENA. */
+    chainLabel: string;
+    /** who is rendering, for the caller zone. Undefined when the caller did not say. */
+    consumer?: ConsumerIdentity;
     /** things a renderer may want to surface. Never thrown; a tooltip must not take a page down. */
     warnings: string[];
 }
@@ -110,7 +151,7 @@ export declare const isNativeKey: (key: string) => boolean;
  * 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;
+export declare function tooltipModel(key: string, values?: Readonly<Record<string, string>>, consumer?: ConsumerIdentity): TooltipModel;
 /**
  * Models for a button that fronts a CHOICE of executions, in the order the ZBOM presents them.
  *
@@ -119,7 +160,7 @@ export declare function tooltipModel(key: string, values?: Readonly<Record<strin
  * 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[];
+export declare function tooltipModels(keys: readonly string[], values?: Readonly<Record<string, string>>, consumer?: ConsumerIdentity): TooltipModel[];
 /**
  * The type row -- rule 3.
  *

package/dist/tooltip.js

@@ -22,12 +22,22 @@
  * 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. THREE WORLDS, and they must be distinguishable at a glance. `ouronet` (the ouronet-ns
- *    surface), `stoa` (StoaChain's own `coin` contract) and `kadena` (Kadena mainnet's `coin`).
- *    They differ in what they cost and what can be previewed. Only `ouronet` has an INFO_ reader
- *    and collects IGNIS; gas is sponsored on the Stoa side regardless -- claiming otherwise tells
- *    a user they are about to spend when they are not. HOW you distinguish them is yours: `kind`
- *    is the canon, the palette is not.
+ * 4. THREE WORLDS, WITH A CANONICAL COLOUR EACH. `ouronet` (blue), `stoa` (gold), `kadena`
+ *    (green). They differ in what they cost and what can be previewed. Only `ouronet` has an
+ *    INFO_ reader and collects IGNIS; gas is sponsored on the Stoa side regardless -- claiming
+ *    otherwise tells a user they are about to spend when they are not.
+ *
+ *    THE PALETTE IS NOW CANON, reversing the 1.4.0 position that it was each app's business.
+ *    The argument then was that a package should not dictate colours inside somebody else's
+ *    design language, and that was right about DECORATION and wrong about this: the colour
+ *    encodes WHICH CHAIN YOUR MONEY IS ON. A user who learns green-means-Kadena in one app and
+ *    meets green-means-something-else in the other has been taught a falsehood by the
+ *    inconsistency, and the two apps share users. A shared vocabulary has to be shared.
+ *
+ * 4b. SAY WHO IS RENDERING. Two applications draw this tooltip, and they draw it over different
+ *    surfaces for the same chains. A caller zone naming the consumer costs one line and answers
+ *    "which app am I looking at" without the user having to infer it from chrome -- which matters
+ *    most in exactly the case where it is hardest, a Codex panel over an OuronetUI page.
  *
  * 0. CHAINWEB ONLY -- the rule that decides whether a tooltip exists at all. This model describes
  *    a PACT call on a Chainweb chain: what function, what arguments, what it costs. A button that
@@ -41,6 +51,37 @@
  */
 import { getEntrypoint, getPreview, tryGetEntrypoint, registry } from "./registry.js";
 import { formatForType } from "./format.js";
+/**
+ * The canonical border colour per chain. USE THESE.
+ *
+ * Not styling: the colour tells a user which chain their money is on, and that vocabulary is
+ * shared between the applications that render it. Two apps teaching different meanings for the
+ * same colour is worse than neither using colour at all, because the user believes the first one
+ * they learned.
+ *
+ *   ouronet  blue    the ouronet-ns surface -- priced, IGNIS, sponsored
+ *   stoa     gold    StoaChain's own coin -- unpriced, no IGNIS, still sponsored
+ *   kadena   green   a DIFFERENT CHAIN -- its own gas, its own balances
+ *
+ * Chosen from what was already in use rather than invented: gold is OuronetUI's STOA accent and
+ * blue its established `#3b82f6`; green is the app's existing success green, which is unused on
+ * any other tooltip surface and therefore free to carry this meaning.
+ */
+export const CHAIN_PALETTE = {
+    ouronet: "#3b82f6",
+    stoa: "#ceac5f",
+    kadena: "#22c55e",
+};
+/** Human label for the chain, for the border-adjacent marker. */
+export const CHAIN_LABEL = {
+    ouronet: "OURONET",
+    stoa: "STOA NATIVE",
+    kadena: "KADENA",
+};
+export const CONSUMERS = {
+    OuronetUI: { name: "OuronetUI", accent: "#d2d3d4" },
+    Codex: { name: "Codex", accent: "#8b5cf6" },
+};
 /** 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;
@@ -124,7 +165,7 @@ const KADENA_GHOST = {
     bool: "false",
     guard: '(read-keyset "ks")',
 };
-function offRegistryModel(key, kind, values) {
+function offRegistryModel(key, kind, values, consumer) {
     const sig = (kind === "stoa" ? STOA_SIGNATURES : KADENA_SIGNATURES)[key];
     if (!sig)
         throw new Error(`offRegistryModel: no signature for "${key}"`);
@@ -132,6 +173,9 @@ function offRegistryModel(key, kind, values) {
     return {
         kind,
         exec: key,
+        chainColor: CHAIN_PALETTE[kind],
+        chainLabel: CHAIN_LABEL[kind],
+        consumer,
         slots: sig.map(([name, type], i) => ({
             index: i + 1,
             name,
@@ -160,10 +204,10 @@ function offRegistryModel(key, kind, values) {
  * 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 = {}) {
+export function tooltipModel(key, values = {}, consumer) {
     const chain = chainOf(key);
     if (chain === "stoa" || chain === "kadena")
-        return offRegistryModel(key, chain, values);
+        return offRegistryModel(key, chain, values, consumer);
     if (chain === undefined && isOffRegistryKey(key))
         throw new Error(`tooltipModel: "${key}" matched no chain. This is a bug in chainOf.`);
     const ep = getEntrypoint(key); // throws, and names near matches, on a stale key
@@ -249,6 +293,9 @@ export function tooltipModel(key, values = {}) {
     return {
         kind: "ouronet",
         exec: `${registry.namespace}.${key}`,
+        chainColor: CHAIN_PALETTE.ouronet,
+        chainLabel: CHAIN_LABEL.ouronet,
+        consumer,
         slots,
         preview,
         // RULE 5: do not fire a read whose answer is a foregone refusal.
@@ -264,10 +311,10 @@ export function tooltipModel(key, values = {}) {
  * 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 = {}) {
+export function tooltipModels(keys, values = {}, consumer) {
     return keys
         .filter((k) => chainOf(k) !== undefined)
-        .map((k) => tooltipModel(k, values));
+        .map((k) => tooltipModel(k, values, consumer));
 }
 /**
  * The type row -- rule 3.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouronet/talos-registry",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "The Ouronet callable surface, generated from the deployed contracts. Supply values; never type a function name.",
   "type": "module",
   "main": "./dist/index.js",