@enc-protocol/emulator -- SDK API Reference

React phone-frame renderer for the UI Kit. Renders resolved UI trees as interactive previews.

Install

npm config set @enc-protocol:registry https://npm-registry.ocrybit.workers.dev/
npm install @enc-protocol/emulator

Peer dependencies: react >= 19, react-dom >= 19

import { RenderNode } from '@enc-protocol/emulator/tree-renderer'
import * as Chrome from '@enc-protocol/emulator/chrome'
import { PostCard, Tabs, EmptyState } from '@enc-protocol/emulator/common'

Table of Contents

1. tree-renderer.tsx -- React Tree Renderer
2. chrome.tsx -- Host Shell Components
3. common.tsx -- Cross-App Primitives
4. dm.tsx -- DM-Specific Components
5. registry.ts -- Component Registry
6. Package Entry (index.ts)

1. tree-renderer.tsx -- React Tree Renderer

Source: sdk-emulator/tree-renderer.tsx

The core renderer that turns UI Kit trees into interactive React DOM. It recursively walks a JSON tree and dispatches each node to the appropriate atom, component, or directory renderer.

RenderNode

The top-level dispatcher component. Determines node type and delegates.

1. If onAction is provided, wraps content in an ActionCtx.Provider so all descendants can access the action callback via React context.
2. Checks node type in order:
   • isComponent(node): Has component property -> RenderComponent
   • hasFiles(node): Has ./ children -> RenderDir
   • isAtom(node): Has atom or typed type -> RenderAtom
   • Otherwise: renders [unknown] error text.

Every rendered element gets a data-path attribute. When a user interacts with an element, the onAction callback is called with the element's data-path (and optionally an input value). The host app translates these paths into state transitions via applyAction.

import { RenderNode } from '@enc-protocol/emulator'
 
function MyApp({ tree, onAction }) {
  return <RenderNode node={tree} path="root" onAction={onAction} />
}

Internal: RenderAtom

Renders leaf nodes (atoms). Not exported directly.

str (text)

Renders as text. If style has primary: true, renders as a Button. Supports grow, size, color, weight, mono, pad style properties.

media (avatar)

Renders as a gradient circle with first-letter monogram. Clickable.

input (text input)

Renders as a text input field. Supports text, file, and textarea types.

• text: Standard pill-shaped input. Fires onAction(path, value) on change, onAction(path + '$submit') on Enter.
• file: File picker display. Shows hash or placeholder.
• textarea: Multiline display (read-only in current impl).

select (single choice)

Renders as a horizontal row of selectable chips.

Fires onAction(path + '$select#x27; + item_key) on chip click.

multiselect (multiple choice)

Same as select but multiple items can be highlighted.

bool (toggle)

Renders as a sliding toggle switch (44x24px).

Fires onAction(path, String(!current)) on click.

slider (range)

Renders as a horizontal bar with min/max labels and current value.

arr (string array)

Renders as a row of teal chips, one per array element.

null (spacer/divider)

Renders as empty space or a 1px separator line.

Internal: RenderComponent

Renders component nodes. Dispatches by node.component name.

header

Renders via DMHeader. Shows title, optional subtitle, optional back button.

tabs

Renders as a horizontal tab bar with accent-colored active indicator. Supports badge counts (numbers in parentheses after label).

Fires onAction(path + '$select#x27; + tab_key) on tab click. Tab key = lowercase, spaces to underscores, badge stripped.

bar / compose_bar

Horizontal flex row: growing input + primary button.

Fires:

• onAction(path + '$input', value) on input change
• onAction(path + '$submit') on button click or Enter

card / list_item

Renders differently based on data shape:

• With body: PostCard (avatar + title + body text)
• Without body: ListItem (title + subtitle + avatar + trailing)

post_card

Always renders as a PostCard (regardless of data shape).

field / form_field

Label text above a rectangle-variant input.

message_bubble

Single chat bubble.

empty_state

Centered message text in muted color.

connect_gate

Full-page connect wallet CTA: avatar, title, subtitle, primary button.

Fires onAction(path + '$connect') on button click.

error_view

Error state: danger-colored title, message, retry button.

card_list

Dynamic list of card items. The most complex component. Each item is rendered based on its shape:

1. Full-width button (accept only, no title/subtitle): Primary button. Fires path + '$accept#x27; + idx.

2. Post card (has body): Avatar + title + body + optional engagement bar (likes/replies). Fires:

   • path + '$avatar#x27; + idx on avatar click
   • path + '#x27; + idx on body click
   • path + '$like#x27; + idx on like click

3. KV detail row (no media/trailing/accept, has subtitle): Label above, monospace value below.

4. App catalog row (accept + media + subtitle, no reject): ListItem with action button. Fires path + '$accept#x27; + idx.

5. Stat row with link (accept, no reject): Title left, accent link right. Fires path + '$accept#x27; + idx.

6. Accept/reject row (both accept and reject): ListItem with two buttons. Fires path + '$accept#x27; + idx or path + '$reject#x27; + idx.

7. Standard list item (fallback): Clickable ListItem. Fires path + '#x27; + idx.

bubble_list

Dynamic list of chat bubbles. Messages are reversed (newest at bottom). Author names are colored (cycling through 6 colors for group chats).

Message object fields: body, outgoing, author, tx_amount, txid.

field_list

Dynamic list of form fields. Each field maintains local React state (controlled input). Uses FieldInput internal component.

Field object: { label, placeholder, value, key }. If key is set, fires onAction(path + '$key#x27; + key, value) on change.

Default (unknown component)

If a component name matches a COMPONENTS catalog entry with a tree definition, it is rendered recursively:

1. Bind data via bindTree.
2. Apply styles via applyStyles.
3. Pass parent data to child components (card_list gets items, bubble_list gets messages, bar gets placeholder/button/value, tabs gets items/active, header gets title/subtitle/back).

If no match: renders [component:name] error text.

Internal: RenderDir

Renders directory (container) nodes. Pure flexbox layout.

Children are rendered via RenderNode with $-separated path segments.

Exported: applyStyles(node, styles, path?) -> any

Duplicated from tree-utils.ts (same implementation). Merges style map into tree nodes. See tree-utils.ts documentation for details.

Exported: validateTree(node, path?) -> string[]

Duplicated from tree-utils.ts. See tree-utils.ts documentation.

2. chrome.tsx -- Host Shell Components

Source: sdk-emulator/chrome.tsx

Chrome components render the host shell around apps -- top bar, wallet connection, phone frame. These are distinct from app-scoped components.

PhoneFrame

iPhone-shaped chrome container (390x844 max). Includes system status bar (time, signal, battery), content area, and bottom system bar with optional home button.

• Top system bar: 9:41 time, dynamic island notch, signal/wifi/battery icons.
• Content area: {children} in a flex column.
• Bottom system bar: Home button (if onHome provided) or swipe indicator.

data-testid: phone-frame

<PhoneFrame onHome={() => navigateHome()}>
  <MyAppContent />
</PhoneFrame>

TopBarContainer

Fixed top bar layout (50px height, flex row).

Renders: Fixed-position bar at top with border-bottom, centered items.

Branding

ENC logo monogram (gradient circle with "E") + "ENC" label.

Props: None.

Spacer

Flex-1 filler for flex rows.

Props: None.

ConnectButton

Connect/Disconnect pill button.

• Connected: Red-tinted "Disconnect" pill.
• Disconnected: Green gradient "Connect" pill.

PubkeyChip

Small monogram circle + truncated pubkey (first 8 chars). Click to copy.

Renders: Rounded pill with gradient circle + monospace truncated key. Copies full pubkey to clipboard on click (both navigator.clipboard and fallback execCommand).

CopyToast

Green confirmation pill, fixed at top center. Auto-dismissing (parent controls visibility).

Renders: Fixed-position green pill with shadow at top: 60px.

WalletChooserModal

Full wallet connection modal. Supports extension, passkey, and dev account options.

interface WalletAccount {
  pubHex: string
  name: string
}
 
interface WalletPasskey {
  credentialId: string
  pubHex: string
  name: string
}

Renders: Centered modal dialog (320px wide, max 80vh scroll) with:

• Header: "Connect Wallet" + description
• Extension button (if available, accent-bordered)
• Account buttons (gradient-circle monogram + name + truncated key)
• Passkey buttons (purple-themed)
• "Use Existing Passkey" button (if onUseExistingPasskey provided)
• "Create Passkey (secure)" button (purple gradient)
• "+ Dev Account (insecure)" button (green gradient)

Backdrop click dismisses. Modal click stops propagation.

QRCodeButton

Top-bar QR icon that opens a modal with a scannable QR code.

Renders: Small icon button (22x22). On click, opens a modal showing:

• "Scan to open on phone" header
• QR code image (260x260 on white background)
• URL text (monospace, word-break)
• "Copy URL" button

ConnectPrompt

Full-page "Connect Wallet" CTA shown when app is opened without wallet.

• Header bar with back arrow + app name
• Centered content: wallet icon, "Connect Wallet" heading, description text, green gradient "Connect Wallet" button

DetectingExtensionScreen

Full-screen loading state while detecting ENC extension.

Props: None.

Renders: Centered spinner + "Detecting ENC Extension..." text.

ExtensionInstallScreen

Full-page extension install guide with dev mode fallback.

• Shield icon
• "ENC Extension Required" heading
• Install instructions
• "Download Extension" button
• Install status + "Copy chrome://extensions" (if installStatus set)
• Developer mode instructions
• "Dev Mode (local keys)" button (purple)
• "Retry Detection" button (muted)

ExtensionUpdateButton

Yellow pill in top bar indicating extension needs update.

Renders: Warning-colored pill: "Update Extension (old -> expected)".

HomeGrid

4-column app launcher tile grid.

interface HomeGridItem {
  name: string
  iconUrl: string
}

• "ENC Emulator" heading
• "N apps loaded" subtitle
• 4-column CSS grid of icon tiles (48x48 images with labels)

3. common.tsx -- Cross-App Primitives

Source: sdk-emulator/common.tsx

Stage-2 axioms used by 2+ unrelated apps. This file must NOT reference any app by name.

PageScaffold

Outer flex container for any app page. Owns text color, font, background.

• 'default': Inherits from parent (undefined background)
• 'chat': TG.chatBg (#0e0e1a)
• 'transparent': Explicit transparent

ScrollBody

Flex-1 body container with optional scroll.

• No scroll: flex: 1; minHeight: 0; display: flex; flexDirection: column
• Scroll: flex: 1; overflowY: auto

FixedItem

Layout wrapper that prevents flex shrinking. Used to pin tabs/bars.

Renders: div with flexShrink: 0.

Stack

Vertical flex layout container.

When onClick is set, adds cursor pointer and bottom border.

Row

Horizontal flex layout container.

Text

Typography axiom. Renders a styled text div.

Size Mapping: sm=12, md=14, lg=16, xl=18. Weight Mapping: regular=400, medium=600, bold=700. Returns null if value is null or empty string. Mono mode: Uses 'SF Mono', monospace with word-break: break-all.

Input

Text input axiom.

Radius: pill=20, rectangle=12. Enter key triggers onSubmit. Style: width: 100%; flex: 1 1 auto; minWidth: 0.

Button

Push-button axiom.

Primary style: accent background, black text. Default style: semi-transparent white background, primary text. Disabled: 50% opacity, not-allowed cursor.

Banner

Clickable callout box with colored border.

• info: accent (teal)
• warning: warning (orange)
• danger: danger (red)
• success: accent (teal, stronger)

If onClick is set, renders as a button element.

Divider

Visual separator (1px line).

Avatar

Gradient circle with first-letter monogram.

Monogram: First character (using Array.from for proper Unicode/emoji handling). ASCII letters are uppercased; emoji/non-ASCII rendered as-is. Font size: Math.round(size * 0.36).

Tabs

Bottom navigation tab bar.

Renders: Horizontal flex row with role="tablist". Each tab is a button with role="tab" and aria-selected. Active tab has accent-colored top border.

ListItem

Generic list row with leading/content/trailing slots.

PostCard

X/Twitter-style timeline post.

Renders: 40px avatar circle + author name + relative time + body text. If body starts with {, attempts JSON parse and joins string values.

MessageBubble

Chat message bubble (Telegram-style).

Outgoing: Right-aligned, green background, checkmark. Incoming: Left-aligned, dark purple background. Transaction: Gradient background, accent border, amount header, truncated tx hash footer.

ComposeBar

Input + submit button pinned to bottom.

Submit guard: Only submits if draft.trim() is non-empty. Pending mode: Shows warning icon + message, hides input.

LoadingSpinner

Animated spinning circle.

EmptyState

Centered muted text for empty lists.

ErrorState

Error display with optional retry button.

AppErrorBoundary

React error boundary that catches render crashes.

On error: Renders ErrorState with "<appName> crashed: <message>". Retry button resets the boundary (re-mounts children).

Header

Generic page header with optional back button and trailing slot.

FormField

Label + input combination.

IconButton

Compact circular action button.

StatusView

Unified loading/error/empty state.

Timestamp

Relative time display.

Output: Ns, Nm, Nh, Nd relative format.

ChatListContainer

Flex-grow scrollable container for chat message lists.

Reverse mode: flex-direction: column-reverse; padding: 8px 10px.

4. dm.tsx -- DM-Specific Components

Source: sdk-emulator/dm.tsx

Stage-1 axioms specific to the DM app, plus re-exports of promoted Stage-2 components.

DMHeader

DM-specific page header with optional avatar.

Same visual layout as Header but with optional inline avatar circle (32x32, gradient background).

EnvelopeBadge

Envelope icon with notification count. Used in header trailing slot.

Active state (count > 0): Red background, red icon stroke, count text. Inactive: Transparent background, secondary icon stroke.

aria-label: "N message request(s)" or "No message requests".

ContactRow

DM contact list item with state indicators.

PENDING state: Shows warning-colored "Awaiting acceptance" text. Outgoing: Prefixes preview with checkmark. data-pub: Set to pub for testing.

MessageBubble (re-export)

Re-exported from common.tsx for backward compatibility. Same component and props as common.MessageBubble.

ChatInputBar

DM-specific chat input bar.

Similar to ComposeBar but with circular send icon button (no label variant). Only sends if draft.trim() is non-empty.

EmptyChat

Centered empty chat state with contact avatar.

Renders: 60px gradient avatar, name, "End-to-end encrypted" label.

LookupResultCard

Found-user card with inline invite form.

Renders: Accent-bordered card with avatar + name + truncated ID + "Found" badge. Below: input ("Say hello...") + "Invite" button.

PublishBanner

Warning banner prompting user to publish profile to registry.

Renders: Warning-themed banner with "Profile not in registry" title, explanation, and "Publish" button (shows "..." when publishing).

DMSetupPage

Profile setup form for first-time DM users.

Renders: Large avatar (80px), "Your Profile" heading, description, centered text input, "Continue" button. Uses local React state for the name field. Only calls onContinue if name is trimmed non-empty.

InviteRow

Message request row with accept/dismiss buttons.

Renders: Truncated monospace pubkey, message text, Accept (accent) and Dismiss (muted) buttons.

DMPageScaffold

DM-specific page wrapper.

DMPageBody

DM page body container (flex-1, column, min-height 0).

5. registry.ts -- Component Registry

Source: sdk-emulator/registry.ts

The protocol surface for manifest-driven rendering. Every visible primitive that an app's manifest can reference MUST be registered here.

REGISTRY_VERSION

const REGISTRY_VERSION = '0.1.0'

Bumped on incompatible changes (prop removal, axiom rename). Additive changes (new axiom, new optional prop) keep the same version.

ComponentSpec Interface

interface ComponentSpec {
  /** React component implementing the axiom */
  Component: React.ComponentType<any>
 
  /** Manifest-prop -> component-prop mapping.
   *  'expr':    evaluated from state/bindings
   *  'action':  wired as callback function
   *  'literal': passed as-is from manifest */
  props: Record<string, 'expr' | 'action' | 'literal'>
 
  /** Optional auto-wired props from runtime */
  wireAuto?: Array<'onBack' | 'lookupName' | 'lookupEnclave' | 'runtime'>
 
  /** If set, children are rendered and passed under this prop name */
  childrenSlot?: string
}

REGISTRY Object

Complete registry of all components. Organized by category:

Common (Stage-2) Axioms

Lowercase Aliases

For backward compatibility with existing manifests: stack, row, text, label, button, banner, divider, timestamp.

Generic Patterns

DM (Stage-1) Axioms

Re-exports from registry.ts

export * as DM from './dm'
export { TG } from './theme'

6. Package Entry (index.ts)

Source: sdk-emulator/index.ts

export * from './common'           // All common components
export * from './dm'               // All DM components
export * as Chrome from './chrome' // Chrome components under namespace
export { TG, type PaletteKey } from '../sdk-ui-kit/theme'
export { REGISTRY, REGISTRY_VERSION, type ComponentSpec } from './registry'

Chrome components are namespaced (Chrome.PhoneFrame, Chrome.ConnectButton, etc.) to avoid naming conflicts with app-level components.