Add interpolated-intent and fallback-list render modes

This PR adds the two clear-signing render modes on top of the value layer (sRFC 39). interpolateIntent renders an instruction's interpolatedIntent template by substituting flat ${data.<argument>} and ${accounts.<account>} placeholders, returning null when the template is absent or a referenced name cannot be resolved so the caller can fall back. listFallback builds the structured fallback list of labelled fields for the instruction's arguments and accounts, honouring skip strategies (including whenInjected), label overrides, and struct flattening with prefixes. Both consume a new formatArgumentValue bridge that maps a decoded value to its type's display node — dispatching to the amount, date-time, duration, and string formatters, resolving linked enums to their variant labels, and degrading to a raw form when no display metadata applies. Defined-type links are followed through a single shared resolveDisplayType helper, and the whole display layer threads one flat DisplayContext (instruction, decoded data, account addresses, provide/inject graph, account fetching, and link resolution) so every piece stays unit-testable ahead of the orchestration PR. These remain internal building blocks, not yet exported from the package. No changeset is included, consistent with the rest of the 1.7.0 stack.

Author: lorisleiva

packages/dynamic-instructions/src/display/format-argument-value.ts

@@ -0,0 +1,111 @@
+import {
+    type EnumTypeNode,
+    isNode,
+    isScalarEnum,
+    pascalCase,
+    resolveNestedTypeNode,
+    titleCase,
+    type TypeNode,
+} from 'codama';
+
+import { isObjectRecord } from '../shared/util';
+import { formatAmountValue, formatDateTimeValue, formatDurationValue, formatStringValue } from './format-value';
+import type { DisplayContext } from './types';
+
+/**
+ * Formats a single decoded value according to the presentation metadata on its type.
+ *
+ * Numbers, strings, and enum variants are rendered through their value-display nodes when
+ * present; `definedTypeLinkNode`s are followed via the context's link resolver so linked
+ * enums resolve to their variants. Any value without applicable display metadata — and any
+ * value whose formatter cannot resolve its inputs — falls back to a raw string form.
+ */
+export async function formatArgumentValue(
+    type: TypeNode,
+    value: unknown,
+    displayContext: DisplayContext,
+): Promise<string> {
+    const resolvedType = resolveDisplayType(type, displayContext);
+
+    if (isNode(resolvedType, 'numberTypeNode') && resolvedType.display && isNumeric(value)) {
+        const formatted = await formatNumber(resolvedType.display, value, displayContext);
+        if (formatted !== null) return formatted;
+    }
+
+    if (isNode(resolvedType, 'stringTypeNode') && resolvedType.display && typeof value === 'string') {
+        return formatStringValue(value, resolvedType.display);
+    }
+
+    if (isNode(resolvedType, 'enumTypeNode')) {
+        return formatEnumValue(resolvedType, value);
+    }
+
+    return rawValue(value);
+}
+
+/**
+ * Resolves nested type wrappers and follows a single `definedTypeLinkNode` to its underlying type.
+ * Shared by the value formatter and the fallback list so links resolve identically in both.
+ */
+export function resolveDisplayType(type: TypeNode, displayContext: DisplayContext): TypeNode {
+    const resolved = resolveNestedTypeNode(type);
+    if (isNode(resolved, 'definedTypeLinkNode')) {
+        const definedType = displayContext.resolveDefinedType(resolved);
+        if (definedType) return resolveNestedTypeNode(definedType.type);
+    }
+    return resolved;
+}
+
+/** Dispatches a number to the matching number-display formatter. */
+async function formatNumber(
+    display: NonNullable<Extract<TypeNode, { kind: 'numberTypeNode' }>['display']>,
+    value: bigint | number,
+    displayContext: DisplayContext,
+): Promise<string | null> {
+    switch (display.kind) {
+        case 'amountNumberDisplayNode':
+            return await formatAmountValue(value, display, displayContext);
+        case 'dateTimeNumberDisplayNode':
+            return formatDateTimeValue(value, display);
+        case 'durationNumberDisplayNode':
+            return formatDurationValue(value, display);
+    }
+}
+
+/**
+ * Formats an enum value using the matched variant's display label.
+ * Scalar enums decode to the variant name; data enums decode to `{ __kind: 'PascalVariant', ... }`.
+ */
+function formatEnumValue(enumType: EnumTypeNode, value: unknown): string {
+    const decodedName = enumVariantName(value);
+    if (decodedName === null) return rawValue(value);
+
+    // Scalar enums decode to the variant name as-is; data enum `__kind` is the PascalCase form.
+    const variant = enumType.variants.find(candidate =>
+        isScalarEnum(enumType) ? candidate.name === decodedName : pascalCase(candidate.name) === decodedName,
+    );
+    if (!variant) return rawValue(value);
+
+    return variant.display?.label ?? titleCase(variant.name);
+}
+
+/** Extracts the variant name from a decoded enum value (scalar name string or data enum `__kind`). */
+function enumVariantName(value: unknown): string | null {
+    if (typeof value === 'string') return value;
+    if (isObjectRecord(value) && typeof value.__kind === 'string') return value.__kind;
+    return null;
+}
+
+/** Renders a value without any display metadata as a safe, human-readable string. */
+function rawValue(value: unknown): string {
+    if (typeof value === 'string') return value;
+    if (typeof value === 'bigint' || typeof value === 'number' || typeof value === 'boolean') {
+        return value.toString();
+    }
+    if (isObjectRecord(value) && typeof value.__kind === 'string') return titleCase(value.__kind);
+    return JSON.stringify(value, (_key, v: unknown) => (typeof v === 'bigint' ? v.toString() : v));
+}
+
+function isNumeric(value: unknown): value is bigint | number {
+    return typeof value === 'bigint' || typeof value === 'number';
+}

packages/dynamic-instructions/src/display/format-value.ts

@@ -6,7 +6,7 @@ import type {
 } from 'codama';
 
 import { resolveInjectedValue } from './resolve-injected-value';
-import type { DisplayResolutionContext } from './types';
+import type { DisplayContext } from './types';
 
 /**
  * Formats an integer as a scaled amount with an optional unit (e.g. `1100000000` → `"1.1 SOL"`).
@@ -19,7 +19,7 @@ import type { DisplayResolutionContext } from './types';
 export async function formatAmountValue(
     value: bigint | number,
     node: AmountNumberDisplayNode,
-    context: DisplayResolutionContext,
+    context: DisplayContext,
 ): Promise<string | null> {
     const decimals = node.decimals ? await resolveInjectedValue(node.decimals, context) : 0;
     if (decimals === null || (typeof decimals !== 'bigint' && typeof decimals !== 'number')) {

packages/dynamic-instructions/src/display/index.ts

@@ -1,3 +1,6 @@
+export * from './format-argument-value';
 export * from './format-value';
+export * from './interpolate-intent';
+export * from './list-fallback';
 export * from './resolve-injected-value';
 export * from './types';

packages/dynamic-instructions/src/display/interpolate-intent.ts

@@ -0,0 +1,48 @@
+import { formatArgumentValue } from './format-argument-value';
+import type { DisplayContext } from './types';
+
+/** Matches a `${root.path}` placeholder, capturing the root and the (flat) path after it. */
+const PLACEHOLDER_PATTERN = /\$\{\s*(data|accounts)\.([a-zA-Z0-9_]+)\s*\}/g;
+
+/**
+ * Renders an instruction's `interpolatedIntent` template into a concrete sentence.
+ *
+ * Placeholders use the flat form `${data.<argument>}` and `${accounts.<account>}`. Each is
+ * replaced by the referent's own presentation: arguments through their value-display nodes,
+ * accounts by their address.
+ *
+ * Returns `null` when the instruction has no `interpolatedIntent`, or when any placeholder
+ * cannot be resolved (an unknown name, or a value whose formatting fails). A `null` result
+ * signals the caller to fall back to the structured field list.
+ */
+export async function interpolateIntent(displayContext: DisplayContext): Promise<string | null> {
+    const template = displayContext.instruction.display?.interpolatedIntent;
+    if (template === undefined) return null;
+
+    // Resolve each distinct placeholder in parallel, then substitute them back into the template.
+    const placeholders = [...template.matchAll(PLACEHOLDER_PATTERN)].filter(
+        ([token], index, all) => all.findIndex(([other]) => other === token) === index,
+    );
+    const resolved = await Promise.all(
+        placeholders.map(async ([token, root, name]) => {
+            return [token, await resolvePlaceholder(root, name, displayContext)] as const;
+        }),
+    );
+
+    if (resolved.some(([, value]) => value === null)) return null;
+    const replacements = new Map(resolved);
+
+    return template.replace(PLACEHOLDER_PATTERN, match => replacements.get(match) ?? match);
+}
+
+/** Resolves a single placeholder to its rendered string, or `null` when it cannot be resolved. */
+async function resolvePlaceholder(root: string, name: string, displayContext: DisplayContext): Promise<string | null> {
+    if (root === 'data') {
+        const argument = displayContext.instruction.arguments.find(arg => arg.name === name);
+        if (!argument || !(name in displayContext.data)) return null;
+        return await formatArgumentValue(argument.type, displayContext.data[name], displayContext);
+    }
+
+    // root === 'accounts'
+    return displayContext.accountAddresses.get(name) ?? null;
+}

packages/dynamic-instructions/src/display/list-fallback.ts

@@ -0,0 +1,83 @@
+import { isNode, type StructTypeNode, titleCase } from 'codama';
+
+import { isObjectRecord } from '../shared/util';
+import { formatArgumentValue, resolveDisplayType } from './format-argument-value';
+import type { DisplayContext, DisplayField } from './types';
+
+/**
+ * Builds the fallback display: a flat, ordered list of labelled fields for an instruction's
+ * arguments and accounts.
+ *
+ * Honours each member's display metadata — `skip` (hidden when `'always'`, or when
+ * `'whenInjected'` and the value was surfaced through the provide/inject graph), `label`
+ * overrides, and struct `flatten`/`flattenPrefix`. The instruction's intent/title is not
+ * included here; the caller composes it around this list.
+ */
+export async function listFallback(displayContext: DisplayContext): Promise<DisplayField[]> {
+    const argumentFieldGroups = await Promise.all(
+        displayContext.instruction.arguments.map(argument => argumentFields(argument, displayContext)),
+    );
+    return [...argumentFieldGroups.flat(), ...accountFields(displayContext)];
+}
+
+/** Produces the display fields for a single instruction argument (one field, or many when flattened). */
+async function argumentFields(
+    argument: DisplayContext['instruction']['arguments'][number],
+    displayContext: DisplayContext,
+): Promise<DisplayField[]> {
+    if (isSkipped(argument.display?.skip, argument.name, displayContext)) return [];
+
+    const value = displayContext.data[argument.name];
+    const resolvedType = resolveDisplayType(argument.type, displayContext);
+    const structType = isNode(resolvedType, 'structTypeNode') ? resolvedType : undefined;
+
+    if (argument.display?.flatten && structType && isObjectRecord(value)) {
+        return await flattenedFields(structType, value, argument.display.flattenPrefix, displayContext);
+    }
+
+    const label = argument.display?.label ?? titleCase(argument.name);
+    return [{ label, value: await formatArgumentValue(argument.type, value, displayContext) }];
+}
+
+/** Lifts a struct's fields into the parent list, prefixing each label and reading nested values. */
+async function flattenedFields(
+    struct: StructTypeNode,
+    value: Record<string, unknown>,
+    prefix: string | undefined,
+    displayContext: DisplayContext,
+): Promise<DisplayField[]> {
+    const visibleFields = struct.fields.filter(field => !isSkipped(field.display?.skip, field.name, displayContext));
+    return await Promise.all(
+        visibleFields.map(async field => {
+            const label = `${prefix ?? ''}${field.display?.label ?? titleCase(field.name)}`;
+            const formatted = await formatArgumentValue(field.type, value[field.name], displayContext);
+            return { label, value: formatted };
+        }),
+    );
+}
+
+/** Produces the display fields for the instruction's accounts. */
+function accountFields(displayContext: DisplayContext): DisplayField[] {
+    return displayContext.instruction.accounts.flatMap(account => {
+        if (isSkipped(account.display?.skip, account.name, displayContext)) return [];
+        const address = displayContext.accountAddresses.get(account.name);
+        if (!address) return [];
+        const label = account.display?.label ?? titleCase(account.name);
+        return [{ label, value: address }];
+    });
+}
+
+/**
+ * Determines whether a member is hidden from the fallback list given its `skip` strategy.
+ * `'always'` always hides; `'whenInjected'` hides when a provider exposes the member's name
+ * (its value is surfaced elsewhere through the provide/inject graph); `'never'`/absent shows.
+ */
+function isSkipped(
+    skip: 'always' | 'never' | 'whenInjected' | undefined,
+    name: string,
+    displayContext: DisplayContext,
+): boolean {
+    if (skip === 'always') return true;
+    if (skip === 'whenInjected') return displayContext.provides.has(name);
+    return false;
+}

packages/dynamic-instructions/src/display/resolve-injected-value.ts

@@ -3,7 +3,7 @@ import type { Address } from '@solana/addresses';
 import { isNode, type Node } from 'codama';
 
 import { isObjectRecord } from '../shared/util';
-import type { DisplayResolutionContext } from './types';
+import type { DisplayContext } from './types';
 
 /**
  * A value resolved from the provide/inject graph for display purposes.
@@ -15,7 +15,7 @@ import type { DisplayResolutionContext } from './types';
 export type ResolvedDisplayValue = Address | bigint | number | string | null;
 
 /**
- * Resolves a node to a concrete display value within a {@link DisplayResolutionContext}.
+ * Resolves a node to a concrete display value within a {@link DisplayContext}.
  *
  * Handles the value/contextual nodes the display layer relies on:
  * - `numberValueNode` / `stringValueNode`: the literal value.
@@ -27,10 +27,7 @@ export type ResolvedDisplayValue = Address | bigint | number | string | null;
  *
  * Returns `null` when the value cannot be resolved so callers can fall back safely.
  */
-export async function resolveInjectedValue(
-    node: Node,
-    context: DisplayResolutionContext,
-): Promise<ResolvedDisplayValue> {
+export async function resolveInjectedValue(node: Node, context: DisplayContext): Promise<ResolvedDisplayValue> {
     if (isNode(node, 'numberValueNode')) {
         return node.number;
     }

packages/dynamic-instructions/src/display/types.ts

@@ -1,6 +1,6 @@
 import type { Account } from '@solana/accounts';
 import type { Address } from '@solana/addresses';
-import type { ProvidedNode } from 'codama';
+import type { DefinedTypeLinkNode, DefinedTypeNode, InstructionNode, ProvidedNode } from 'codama';
 
 /**
  * Fetches and decodes the account at a given address, returning Kit's decoded `Account`
@@ -17,21 +17,46 @@ import type { ProvidedNode } from 'codama';
 export type FetchAccountDataFn = (address: Address) => Promise<Account<object> | null>;
 
 /**
- * The contextual environment in which display values are resolved.
+ * Resolves a `definedTypeLinkNode` to its underlying `DefinedTypeNode`, or `undefined` when
+ * the link cannot be resolved.
  *
- * Mirrors the provide/inject pattern: an instruction (or other host) exposes named values
- * through `provides`, and reusable types pull them by key via `injectedValueNode`. Resolving
- * those keys may also require reading account state, so the context carries the addresses of
- * the surrounding instruction's accounts plus the `fetchAccountData` hook.
+ * Lets the display layer follow links (e.g. an argument typed as a linked enum) without
+ * depending on `NodePath` construction. The orchestrator backs this with a `LinkableDictionary`
+ * populated from the root; tests can supply a simple map-backed resolver.
+ */
+export type ResolveDefinedTypeFn = (link: DefinedTypeLinkNode) => DefinedTypeNode | undefined;
+
+/** A single labelled field of the fallback display list (e.g. `{ label: 'Amount', value: '1.5 USDC' }`). */
+export type DisplayField = {
+    /** The human-readable label for the field. */
+    readonly label: string;
+    /** The formatted value for the field. */
+    readonly value: string;
+};
+
+/**
+ * Everything needed to present one concrete instruction.
+ *
+ * A single context threaded through the whole display layer: the static `instruction`
+ * definition, its decoded argument `data` (a flat record keyed by argument name), the
+ * concrete account addresses (keyed by account name; the instruction supplies their order),
+ * the provide/inject graph, account fetching, and link resolution. Lower-level helpers read
+ * only the parts they need.
  *
- * The orchestrator assembles this from a parsed instruction; it is kept explicit here so the
- * resolution and formatting layers can be exercised in isolation.
+ * The orchestrator assembles this from a parsed instruction; it is kept explicit so every
+ * layer can be exercised in isolation.
  */
-export type DisplayResolutionContext = {
-    /** Addresses of the surrounding instruction's accounts, keyed by account name. */
+export type DisplayContext = {
+    /** Concrete account addresses, keyed by account name. */
     readonly accountAddresses: ReadonlyMap<string, Address>;
+    /** The decoded argument values, keyed by argument name. */
+    readonly data: Record<string, unknown>;
     /** Fetches and decodes account data; absent when running fully offline. */
     readonly fetchAccountData?: FetchAccountDataFn;
+    /** The static instruction definition being presented. */
+    readonly instruction: InstructionNode;
     /** Values exposed by the surrounding host, keyed by the name they are provided under. */
     readonly provides: ReadonlyMap<string, ProvidedNode>;
+    /** Resolves any `definedTypeLinkNode` reached while following an argument's type. */
+    readonly resolveDefinedType: ResolveDefinedTypeFn;
 };