@pouchy_ai/companion-sdk 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -12,6 +12,32 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.42.0] - 2026-07-25
+
+Additive: the Instant UI ⇄ Google A2UI v0.9 projection ships in the package.
+No wire-protocol bump (`PROTOCOL_VERSION` stays 1); no existing export moved.
+
+- **`toA2UI` / `fromA2UI`** — project an Instant UI panel (the
+  `companion.ui_action` `payload.interface`) losslessly to Google's A2UI v0.9
+  flat wire format and back, so a renderer built against the A2UI catalog can
+  draw Pouchy panels with the adapter in front. Previously the adapter lived
+  only in the app repo (`src/lib/genui/a2ui-adapter.ts`) and integrators had
+  to vendor the file; that path now delegates to this package. Concepts A2UI
+  has no standard slot for (Progress, Accordion, area/pie chart kinds,
+  `computed`, `when`, tones, etc.) ride a per-component `_pouchy` extension —
+  A2UI renderers ignore it; `fromA2UI` reconstructs the exact panel from it.
+- **Instant UI panel types** — the strict panel/node type family
+  (`DynamicInterface`, `GenuiNode`, …) and the `INSTANT_UI_NODE_TYPES`
+  catalog (as data, for renderer capability checks) are exported alongside.
+  `toA2UI` accepts either the strict panel type or the loose
+  `payload.interface` exactly as `onRender` delivers it. Embedded Button /
+  table-row actions are typed as an opaque `EmbeddedAction { type }` — hosts
+  hand them back, never interpret them.
+- **CDN bundle size** — the projection adds ~1.7KB gzip to the min bundle
+  (~15.7KB total) / ~3.2KB to the full one (~32.2KB); the size-gate budgets
+  were raised consciously (14→17KB min, 29→35KB full) per the gate's
+  contract.
+
 ## [0.41.0] - 2026-07-25
 
 Additive: call-window generation fencing + world-state replay observability.

package/README.md

@@ -169,6 +169,20 @@ Reference renderers ship in [`examples/`](../../examples): `web-instant-ui` (van
 `native-instant-ui` (SwiftUI + Jetpack Compose), and `cli-skills` (terminal +
 local/device skills).
 
+**Already have an [A2UI](https://github.com/google/A2UI)-catalog renderer?**
+(0.42.0) `toA2UI(payload.interface)` projects any panel losslessly to Google's
+A2UI v0.9 flat wire format (standard component/field names; Pouchy-only
+concepts ride a `_pouchy` extension A2UI renderers ignore), and `fromA2UI`
+ingests a surface back. `INSTANT_UI_NODE_TYPES` lists the atom catalog as data
+for capability checks. Embedded Button / table-row actions are opaque
+`EmbeddedAction { type }` values — hand them back to the companion, never
+interpret them.
+
+```ts
+import { toA2UI } from '@pouchy_ai/companion-sdk';
+companion.onRender(({ interface: ui }) => myA2uiRenderer.render(toA2UI(ui)));
+```
+
 ## Client methods (beyond the quickstart)
 
 | Method | What it does |

package/dist/a2ui.d.ts

@@ -0,0 +1,216 @@
+import type { RenderInterfacePayload } from './protocol.js';
+export type StateValue = string | number | boolean;
+/** A prop value that is either a literal or a live reference to a state key. */
+export type ValueRef<T extends StateValue> = T | {
+    $state: string;
+};
+/** An action embedded in a Button / Table row — carried OPAQUELY through the
+ *  projection (stuffed into the A2UI event context verbatim, restored on the
+ *  way back). The app narrows it to its full AgentAction union; hosts treat it
+ *  as data to hand back, never to interpret. */
+export interface EmbeddedAction {
+    type: string;
+}
+export type GenuiTextTone = 'default' | 'muted' | 'strong';
+export type GenuiButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
+export type GenuiProgressVariant = 'default' | 'affection' | 'energy' | 'health' | 'tier';
+export interface GenuiTextNode {
+    type: 'Text';
+    text?: string;
+    /** Template with `{key}` placeholders resolved against interface state. */
+    template?: string;
+    tone?: GenuiTextTone;
+}
+export interface GenuiButtonNode {
+    type: 'Button';
+    label: string;
+    variant?: GenuiButtonVariant;
+    action: EmbeddedAction | null;
+}
+export interface GenuiProgressNode {
+    type: 'Progress';
+    value: ValueRef<number>;
+    max?: number;
+    variant?: GenuiProgressVariant;
+}
+export interface GenuiIconNode {
+    type: 'Icon';
+    name: string;
+    size?: number;
+}
+export interface GenuiSliderNode {
+    type: 'Slider';
+    bind: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    label?: string;
+}
+export interface GenuiSwitchNode {
+    type: 'Switch';
+    bind: string;
+    label?: string;
+}
+export interface GenuiSelectOption {
+    value: string;
+    label: string;
+}
+export interface GenuiSelectNode {
+    type: 'Select';
+    bind: string;
+    options: GenuiSelectOption[];
+    placeholder?: string;
+}
+export interface GenuiTextInputNode {
+    type: 'TextInput';
+    bind: string;
+    label?: string;
+    placeholder?: string;
+    multiline?: boolean;
+    maxLength?: number;
+}
+export type GenuiGroupDirection = 'row' | 'column';
+export interface GenuiGroupNode {
+    type: 'Group';
+    direction: GenuiGroupDirection;
+    gap?: number;
+    wrap?: boolean;
+    children: GenuiNode[];
+}
+export interface GenuiImageNode {
+    type: 'Image';
+    src: string;
+    alt?: string;
+    ratio?: number;
+}
+export interface GenuiVideoNode {
+    type: 'Video';
+    src: string;
+    ratio?: number;
+}
+export interface GenuiAudioNode {
+    type: 'AudioPlayer';
+    src: string;
+    title?: string;
+}
+export interface GenuiMarkdownNode {
+    type: 'Markdown';
+    text: string;
+}
+export type GenuiChartKind = 'bar' | 'line' | 'area' | 'pie' | 'donut';
+export interface GenuiChartDatum {
+    label?: string;
+    value: number;
+}
+export interface GenuiChartNode {
+    type: 'Chart';
+    chart: GenuiChartKind;
+    data: GenuiChartDatum[];
+    max?: number;
+    title?: string;
+}
+export interface GenuiTableNode {
+    type: 'Table';
+    columns: string[];
+    rows: string[][];
+    title?: string;
+    rowActions?: (EmbeddedAction | null)[];
+}
+export interface GenuiDatePickerNode {
+    type: 'DatePicker';
+    bind: string;
+    label?: string;
+    min?: string;
+    max?: string;
+}
+export interface GenuiWhen {
+    key: string;
+    equals?: StateValue;
+    truthy?: boolean;
+}
+export interface GenuiTab {
+    label: string;
+    children: GenuiNode[];
+}
+export interface GenuiTabsNode {
+    type: 'Tabs';
+    tabs: GenuiTab[];
+    bind?: string;
+}
+export interface GenuiAccordionSection {
+    label: string;
+    children: GenuiNode[];
+    open?: boolean;
+}
+export interface GenuiAccordionNode {
+    type: 'Accordion';
+    sections: GenuiAccordionSection[];
+    multi?: boolean;
+}
+export interface GenuiDividerNode {
+    type: 'Divider';
+}
+export interface GenuiCardNode {
+    type: 'Card';
+    title?: string;
+    children: GenuiNode[];
+}
+export type GenuiNode = (GenuiTextNode | GenuiButtonNode | GenuiProgressNode | GenuiIconNode | GenuiSliderNode | GenuiSwitchNode | GenuiSelectNode | GenuiTextInputNode | GenuiGroupNode | GenuiImageNode | GenuiChartNode | GenuiTableNode | GenuiDatePickerNode | GenuiTabsNode | GenuiAccordionNode | GenuiDividerNode | GenuiCardNode | GenuiVideoNode | GenuiAudioNode | GenuiMarkdownNode) & {
+    when?: GenuiWhen;
+};
+export interface GenuiComputed {
+    op: 'mul' | 'add' | 'sub' | 'div';
+    args: (string | number)[];
+    round?: number;
+}
+/** The Instant UI panel — what `companion.ui_action` carries in
+ *  `payload.interface` (typed strictly here; the event payload declares the
+ *  loose wire shape). */
+export interface DynamicInterface {
+    title?: string;
+    nodes: GenuiNode[];
+    state?: Record<string, StateValue>;
+    computed?: Record<string, GenuiComputed>;
+    reportChanges?: boolean;
+    allowedActions?: string[];
+}
+/** What `toA2UI` accepts: the strict panel type, or the loose
+ *  `payload.interface` exactly as `onRender` delivers it (already validated
+ *  and clamped server-side, so the structural cast inside is safe). */
+export type InstantUIInput = DynamicInterface | RenderInterfacePayload['interface'];
+/** The Instant UI node-type catalog, as data — drift-pinned against the app's
+ *  canonical GENUI_NODE_SET so the mirror can never silently lag a new atom. */
+export declare const INSTANT_UI_NODE_TYPES: readonly ["Text", "Button", "Progress", "Icon", "Slider", "Switch", "Select", "TextInput", "Group", "Image", "Chart", "Table", "DatePicker", "Tabs", "Accordion", "Divider", "Card", "Video", "AudioPlayer", "Markdown"];
+/** A2UI binding: a literal, a JSON-Pointer data binding, or a function call. */
+export type A2UIValue = StateValue | {
+    path: string;
+} | {
+    call: string;
+    args?: unknown;
+};
+export interface A2UIComponent {
+    id: string;
+    /** A2UI component type, e.g. "Text" / "Button" / "Row" / "pouchy/Progress". */
+    component: string;
+    /** Standard A2UI property bag (component-specific; see the mapping per type). */
+    [key: string]: unknown;
+    /** Pouchy-only reconstruction data for concepts A2UI has no standard for.
+     *  A2UI renderers ignore it; fromA2UI() uses it to rebuild the exact node. */
+    _pouchy?: Record<string, unknown>;
+}
+/** An A2UI surface = a flat component map + a root id + the data model. The
+ *  `pouchy` block carries panel-level extensions A2UI has no slot for. */
+export interface A2UISurface {
+    root: string;
+    components: Record<string, A2UIComponent>;
+    dataModel: Record<string, StateValue>;
+    pouchy?: {
+        title?: string;
+        computed?: Record<string, GenuiComputed>;
+        reportChanges?: boolean;
+        allowedActions?: string[];
+    };
+}
+export declare function toA2UI(input: InstantUIInput): A2UISurface;
+export declare function fromA2UI(surface: A2UISurface): DynamicInterface;
+//# sourceMappingURL=a2ui.d.ts.map

package/dist/a2ui.d.ts.map

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