PocketJS Native Contract: ui.* Op Surface Reference

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pocket-stack/pocketjs/llms.txt

Use this file to discover all available pages before exploring further.

​

The three rules

​

The op table

export interface HostOps {
  createNode(type: number): number;
  destroyNode(id: number): void;
  insertBefore(parent: number, child: number, anchorOr0: number): void;
  removeChild(parent: number, child: number): void;
  setStyle(id: number, styleId: number): void;
  setProp(id: number, propId: number, value: number): void;
  setText(id: number, str: string): void;
  replaceText(id: number, str: string): void;
  uploadTexture(buf: Uint8Array, w: number, h: number, psm: number): number;
  setImage(id: number, texHandle: number): void;
  setSprite(id: number, atlas: number, frames: number, cols: number, step: number): void;
  animate(id: number, propId: number, to: number, durMs: number, easing: number, delayMs: number): number;
  cancelAnim(animId: number): void;
  setFocus(idOr0: number): void;
  loadStyles?(buf: Uint8Array): void;
  loadFontAtlas?(buf: Uint8Array): void;
  measureText(str: string, fontSlot: number): number;
}

​

Prop value encoding

• f32 props (dimensions, scalars, degrees) pass through as-is.
• Color props travel as their u32 ABGR bits (0xAABBGGRR — the PSP GE COLOR_8888 layout). A '#rgb', '#rrggbb', or '#rrggbbaa' string is parsed by parseHexColor with full-string hex validation, so #ff00zz throws rather than silently painting a prefix match.
• Int/enum props travel as their u32 ordinal.

​

Generation-tagged node ids

id = (generation << ID_SLOT_BITS) | slot;
// ID_SLOT_BITS = 20  →  slot occupies the low 20 bits (mask 0xFFFFF)

• Bit 31 stays 0, so ids are always positive i32.
• 0 is “no node” — insertBefore anchor 0 = append; setFocus 0 = clear focus.
• ROOT_ID = 1 (slot 1, generation 0): the pre-created full-screen root, a flex column. Your tree mounts under it.
• MAX_TREE_DEPTH = 64. insertBefore past the cap is a silent no-op, which bounds every recursive tree walk (layout, paint, subtree destroy) so a runaway tree cannot overflow the small PSP thread stacks.

​

The JS mirror tree

interface NodeMirror {
  id: number;                          // native generation-tagged id
  type: number;                        // NODE_TYPE ordinal
  parent: NodeMirror | null;
  children: NodeMirror[];
  text?: string;                       // text nodes only
  domNodeType?: number;                // Vue Vapor DOM-compat nodeType
  domTag?: string;                     // Vue Vapor DOM-compat tag name
  domAttrs?: Record<string, unknown>;  // Vue Vapor DOM-compat attribute cache
  domData?: string;                    // Vue Vapor DOM-compat comment payload
  focusable?: boolean;
  onPress?: (() => void) | undefined;
}

​

Two host kinds

​

Frame order on PSP

sceCtrlRead
  ↓
sceGuStart                   begin the GE display list (main.rs owns it)
  ↓
frame(buttons)               edge-detect input; run Solid/Vapor effects for
                             changed signals (the only ops emitted this frame);
                             runSweep() runs last inside this call
  ↓
drain pending jobs           while JS_ExecutePendingJob(rt, &ctx) > 0
                             (promise microtasks — polyfilled queueMicrotask)
  ↓
core.tick(1/60)              advance every anim/spring track at FIXED_DT
  ↓
layout (if dirty)            taffy re-run + text re-measure, only if a
                             layout-dirtying prop changed this frame
  ↓
DrawList                     tree walk → flat Vec<u32> ops, CPU-clipped to
                             [0, 480] × [0, 272]
  ↓
ge::render                   DrawList → sceGu draw calls
  ↓
sceGuFinish / Sync / WaitVblank / Swap

• The sweep runs inside frame(), as the very last thing before returning. A remove-then-reinsert within one frame (a <For> reorder, a <Show> toggle) never destroys a live node.
• Fixed dt = 1/60 s. core.tick always advances by exactly FIXED_DT, never wall-clock delta. Frame content is a pure function of tick index, which is exactly what makes byte-exact PNG goldens possible across PSP, PPSSPP, and headless Bun.
• Layout is conditional. Only a change to a LAYOUT_DIRTYING prop (sizes, padding, flex props, fontSlot, tracking, lineHeight) re-runs taffy. Transform and color changes are paint-only. Prefer transforms for animation.
• Backends never own the display list. sceGuStart/Finish live in native/src/main.rs; the GE backend only translates a pre-clipped DrawList into draw calls.

​

Node reclamation

function removeNodeImpl(parent, node) {
  notifyDetached(node);             // focus repair, before the unlink
  getOps().removeChild(parent.id, node.id);
  unlink(node);                     // drop from JS mirror parent
  sweepSet.add(node);               // reclaim at frame end unless re-attached
}

​

retain() and release()

import { retain, release } from "@pocketjs/framework";

retain(node);   // detached but preserved; sweep skips it and any subtree containing it
// ... frames later ...
release(node);  // undo; if still detached, it re-enters the next sweep

​

The spec as single source of truth

1. spec/gen-rust.ts reads spec/spec.ts and code-generates core/src/spec.rs deterministically.
2. core/src/spec.rs is committed. It is the file the Rust compiler reads.
3. test/contract.ts re-runs gen-rust.ts in-memory and byte-compares the result against the committed file. If they differ the CI build fails with a clear “run bun spec/gen-rust.ts and commit” message.

​

Text model

​

Performance budget

​

PSP memory model

1. A vendored rust-psp fork gains an external-global-alloc feature that cfg-gates out its #[global_allocator].
2. native/src/alloc.rs installs the PocketJS global allocator, backed by arena::alloc/dealloc — the same single kernel block QuickJS uses. Core, QuickJS, and newlib all draw from one arena.
3. arena.rs’s ensure_init calls sceKernelAllocPartitionMemory / sceKernelGetBlockHeadAddr directly to avoid recursion back through alloc::alloc.
4. A 2 MB margin is reserved for the GE display list and stack safety.

• JS runs on a 2 MB USER | VFPU worker; the main stack is 256 KB. MAX_TREE_DEPTH = 64 keeps every recursive walk inside it.
• GE buffers are 16-byte aligned with a dcache writeback per batch.
• 2D vertex coords are i16; the core’s CPU clip stage guarantees in-range values so the GE never wraps a coordinate.
• Textures are power-of-two, ≤ 512 per side, sampled from main RAM.