API reference
The primary app-facing exports of @pocketjs/framework, grouped by import
path. Signatures are TypeScript-style; defaults are noted in parentheses.
Framework-internal and tests/debug helpers are not exhaustive here. For conceptual walkthroughs see Components,
Reactivity, Animation, and
Input & focus.
| Import path | Exports |
|---|---|
@pocketjs/framework |
mount, render, host/runtime helpers, types |
@pocketjs/framework/components |
View, Text, Image, Sprite, Screen, Focusable, FocusScope, FocusGrid, ActionHandler, Portal, AuxiliarySurface, AuxiliaryPortal, Modal, ActionBar, Named, Grid, Lazy, Gallery, DeepZoom, useViewport (Solid) |
solid-js |
createSignal, createEffect, createMemo, onMount, onCleanup, batch, untrack, Show, For, Index, Switch, Match |
vue |
defineComponent, ref, computed, watchEffect, onMounted, onScopeDispose |
octane |
useState, useEffect, useMemo, useRef, useLayoutEffect, useEffectEvent |
@pocketjs/framework/animation |
animate, spring, jump, cancelAnim, animationClass |
@pocketjs/framework/physics |
createWorld, hasPhysics, World, Body, Collider, Zone, Emitter and their option types — see Physics |
@pocketjs/framework/lifecycle |
onFrame, onButtonPress, analogX, analogY, analogRaw, createSpriteAnimation, pushButtonHandlerBlock (Octane builds: useFrame, useButtonPress, useSpriteAnimation) |
@pocketjs/framework/input |
BTN, touches, auxiliaryTouches, onTextEvent, hasTextInput, pointer, onScroll, focusNode, getFocused, pressNode, setActiveNode, pushFocusScope, pushFocusGrid, pushFocusController, hitFocusable, hitNode, enableCursor, cursorX, cursorY |
@pocketjs/framework/gesture |
createGesture, attachGesture, pushTouchBlock, gesture types (Solid and Vue Vapor) |
@pocketjs/framework/kinetics |
createScroller, bindDpadScroll, Scroller / ScrollerOptions / ScrollerState types (Solid and Vue Vapor) |
@pocketjs/framework/osk |
Osk, TextField, createOsk, OSK_H, OSK_LAYERS, OSK_LAYOUTS, oskPanelHeight, resetPanelMemory (Solid) |
@pocketjs/framework/virtual-list |
VirtualList, VirtualListProps, VirtualListHandle (Solid) |
@pocketjs/framework/display |
auxiliaryViewport, hasAuxiliarySurface |
@pocketjs/framework/platform |
platform, hasFeature |
@pocketjs/framework/modality |
modality, presentation, screen, surfaceHasTouch, supports, glyph |
@pocketjs/framework/actions |
useActions, ACTION_BUTTONS, ACTION_INTENTS, HOLD_SECONDS (Solid) |
@pocketjs/framework/classic |
ClassicBar, ClassicFooter, ClassicList, ClassicSelection, ClassicSpinner, ClassicSkeleton, ClassicButton, ClassicFace, ClassicPanel, ClassicSheet, CLASSIC (Solid) |
@pocketjs/framework/clock |
simulationHz, ticksPerFrame, virtualFrame, virtualNow, after |
@pocketjs/framework/effects |
installEffectDriver, runEffect, effect types |
@pocketjs/framework/db |
Database, Statement, SqlValue, SqlParams, RunResult |
@pocketjs/framework/fs |
file, write, usage, and the node:fs sync subset (readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync, rmSync, renameSync, statSync, existsSync) |
@pocketjs/framework/audio |
decodeWav, createWavPlayer, WavPcm / WavPlayer types |
@pocketjs/framework/devtools |
initDevtools, wrapFrameHandler, tape expanders — see DevTools |
@pocketjs/framework/hot |
text, prop |
@pocketjs/framework/host-config |
defineHostConfig, isBuiltinHostId, cargo, cmake, make, compilerOnly, types AppConfig, AnimationTheme, AppViewport, SurfacesSpec, WorkerDeclarationSource |
@pocketjs/framework/plan |
resolveAppPlan, ResolvedBuildPlan, plan hashing and verification, extractHostBuildInputs, hostBuildEnvironment, vitaTitleId |
framework/compiler/subpaths.ts is the registry these paths are declared in —
one row per module, and a build resolves nothing that has no row. The rows it
carries beyond this table (/config, /host, /bundle, /prelude,
/renderer, /idf-host, /vita-package) are build and host-author surface
rather than app API.
@pocketjs/framework
The runtime entry point: mount an app, tear it down, and reach the lower-level host, sweep, style, and pack utilities.
mount
function mount(code: () => unknown, opts?: MountOptions): () => voidApp-level entry point for demo/application bundles. Resolves ops from opts.ops or globalThis.ui, loads opts.pak (when given), uploads the pack's images on injected hosts, feeds the default generated style table (opts.styles ?? STYLE_IDS), and mounts code. Returns a disposer that unmounts and destroys the app subtree. Throws if neither opts.ops nor globalThis.ui is present.
Solid entries pass a closure (mount(() => <App />)); Vue Vapor and Octane
entries pass the component itself (mount(App)). In Octane, JSX inside a
call-argument arrow is a compile error, so mount(App) is the only valid
entry shape.
render
function render(code: () => unknown, opts?: RenderOptions): () => voidLower-level mount: detects and installs the host, wires the style resolver, registers opts.styles, feeds styles/atlases from the pack on injected hosts, builds the app + overlay layers, installs the per-frame handler, and mounts code. Returns a disposer. mount calls render; call render directly when you supply your own ops/styles.
RenderOptions / MountOptions
MountOptions is an alias of RenderOptions.
| Field | Type | Description |
|---|---|---|
ops |
HostOps |
web/wasm/test hosts inject their op surface here; omit on native QuickJS hosts (globalThis.ui). |
styles |
Record<string, number> |
class-literal → styleId table (styles.generated.ts). |
pak |
ArrayBuffer |
app pack; defaults to globalThis.__pak when present. |
Host helpers
function detectHost(injected?: HostOps): Host
function installHost(host: Host): void
function getOps(): HostOps
function onViewport(listener: (w: number, h: number) => void): () => voiddetectHost resolves the active host — injected ops win, otherwise
globalThis.ui (PSP/Vita QuickJS); throws when neither exists. installHost
sets the active host (called by render). getOps returns the installed op
surface. Native bundles built from a build plan validate ui.__host and
ui.__hostAbi before mounting. See Native contract
for the full HostOps surface.
onViewport calls listener with the new logical size on every
resizeViewport, after the root layers and ui.__viewport carry that size,
and returns the function that removes it. It is the framework-neutral form of
useViewport. A host without display.viewport.live
never calls it.
HostOps
The synchronous ui.* op surface a host installs. Node ids are
generation-tagged positive i32 values and reserve 0 for "none"; texture
handles have separate 0-based or generation-tagged contracts. Its TypeScript
declaration is HostOps in framework/src/host.ts, and the
Native contract page owns the wire: every op number,
signature, and which ops a host may omit.
Host
interface Host {
ops: HostOps;
kind: "native" | "injected";
target: string;
strict: boolean;
}kind describes who owns the transport, not the target. Native PSP and Vita
hosts are non-strict and count an unknown class or texture; injected
web/wasm/test hosts throw. target normally carries "psp", "vita", or
"injected"; a pre-contract native host reports "unknown", and a custom
injected host may supply another identifier.
End-of-frame sweep
function retain(node: NodeMirror): void
function release(node: NodeMirror): void
function runSweep(): voidretain keeps a detached subtree alive across frames (skips the sweep); release undoes it so a still-detached node re-enters the next sweep. runSweep destroys every subtree removed during the frame and still detached — the runtime calls it once per frame after user code and input, so remove-then-reinsert (Solid moves) never destroys live nodes. Reach for these only when hand-managing detached subtrees.
registerTexture
function registerTexture(key: string, handle: number): voidBind an image key (the src string) to an uploadTexture handle so <Image src="key"> resolves through the renderer's texture registry.
missCounters
const missCounters: { unknownClass: number; unknownTexture: number }On a non-strict native host, an unknown class or texture increments a counter instead of throwing. Read it to diagnose missing styles/images without crashing hardware.
Styles
function registerStyles(table: Record<string, number>): void
function resolveStyle(cls: string): number | undefinedregisterStyles loads a class-literal → styleId table (the compiler's STYLE_IDS); it also registers a token-sorted alias so "a b" resolves the id for "b a". resolveStyle returns the styleId for a class string, or undefined if the compiler never saw it (or the token reordering is ambiguous). See Styling.
Data pack (pak)
function pakEntries(prefix?: string): string[]
function pakGet(key: string): Uint8Array
function loadPack(ab: ArrayBuffer): void
function resetPack(): voidpakEntries lists entry keys starting with prefix (default: all keys), sorted. pakGet returns a fresh copy of a blob's bytes, throwing on a missing key. loadPack explicitly loads a pack (web host after fetch, or tests), replacing any prior. resetPack drops the cached parsed pack. See Build pipeline.
NodeMirror
interface NodeMirror {
id: number; // native generation-tagged node id
type: number; // spec NODE_TYPE ordinal
parent: NodeMirror | null;
children: NodeMirror[];
text?: string; // text nodes only
focusable?: boolean; // focus traversal membership
onPress?: (() => void) | undefined; // activation: CIRCLE, tap, or cursor click
}The JS mirror of a native node. A ref receives one; animate, spring, focusNode, pushFocusScope, and pushFocusGrid all accept one.
@pocketjs/framework/components
Platform primitives and higher-level components. Solid control-flow components
(Show, For, Index, Switch, Match) are not exported here; import them
directly from solid-js.
Primitives
function View(props: ViewProps): JSX.Element
function Text(props: TextProps): JSX.Element
function Image(props: ImageProps): JSX.Element
function Sprite(props: SpriteProps): JSX.ElementThe host primitives, wrapped React Native-style. View is the flex container/box, Text renders baked-font text, Image draws an uploaded texture by src key, and Sprite draws an auto-playing animation from a baked sprite atlas by sprite key.
ViewProps
| Prop | Type | Description |
|---|---|---|
class |
string |
Tailwind-subset class literal. |
style |
Record<string, number | string> |
Inline spec props (escape hatch). |
onPress |
() => void |
Fired when the node is activated: CIRCLE while focused, a touch tap on the node, or a cursor click. See App shell. |
focusable |
boolean |
Joins d-pad focus traversal. |
ref |
(node: NodeMirror) => void | NodeMirror |
Node handle. |
children |
JSX.Element |
Child nodes. |
debugName |
string |
Semantic name in the DevTools tree (mirror-only, zero native cost). |
TextProps — class, style, ref, children, debugName.
ImageProps — class, src (string), style, ref, debugName.
SpriteProps — class, sprite (string — a ui:sprite.<name> atlas key), frameStep (number), style, ref, debugName.
Sprite is a native animated primitive: its atlas (a pow2 texture holding a grid of frames) is baked into the pak, and the Rust core advances the frame cell from its own tick counter — deterministic and with zero per-frame JS. It auto-plays from the first frame the moment it is displayed, so a sprite revealed by paging or a Show/Lazy starts animating on its own. Bake atlases by listing them in a demo's sprites.json ({ "<atlas>.png": { cols, rows, frames, step } }); step is core ticks per frame, so the sprite runs at tick rate / step fps (step: 2 is 30 fps on a 60 Hz bundle). frameStep overrides the sprites.json step at runtime and is clamped to the core's 1–65535 tick range. See apps/gallery (its covers are shader-baked animated sprites).
Screen
function Screen(props: ScreenProps): JSX.Element // ScreenProps extends ViewPropsA full-screen root View. Defaults class to "relative flex-col w-full h-full bg-slate-50 overflow-hidden" when none is given.
Focusable
interface FocusableProps extends ViewProps { onPress?: () => void }
function Focusable(props: FocusableProps): JSX.ElementA View with focusable: true. onPress is the activation handler: CIRCLE
while the node is focused, a touch tap on the node, or a cursor click all
enter it through the same path. See App shell.
FocusScope
interface FocusScopeProps extends ViewProps, FocusScopeOptions {
active?: boolean | (() => boolean);
}
function FocusScope(props: FocusScopeProps): JSX.ElementRestricts d-pad traversal and CIRCLE to its subtree while active (default true). Adds autoFocus / restoreFocus from FocusScopeOptions. Internally pushes/pops via pushFocusScope.
FocusGrid
interface FocusGridProps extends ViewProps, FocusGridOptions {
active?: boolean | (() => boolean);
}
function FocusGrid(props: FocusGridProps): JSX.ElementGives its subtree row/column d-pad semantics while active. Requires columns; wrap (default false) wraps at row ends. Internally pushes/pops via pushFocusGrid.
ActionHandler
interface ActionHandlerProps extends ButtonPressOptions {
button: number; // BTN mask
onPress: (pressed: number, buttons: number) => void;
children?: JSX.Element;
}
function ActionHandler(props: ActionHandlerProps): JSX.ElementDeclarative wrapper over onButtonPress: fires onPress on the button edge.
Inherits allowWhenBlocked, active, and latched from
ButtonPressOptions. Renders children (or nothing).
Portal
interface PortalProps { children?: JSX.Element | (() => JSX.Element) }
function Portal(props: PortalProps): JSX.ElementRenders children into the full-screen overlay root (above the app layer, zIndex 1000) instead of the local tree. Cleans up its host node on unmount.
AuxiliarySurface
interface AuxiliarySurfaceProps { children?: JSX.Element | (() => JSX.Element) }
function AuxiliarySurface(props: AuxiliarySurfaceProps): JSX.ElementRenders children into the independent application layer of the resolved
auxiliary display. The component requires display.auxiliary; mounting it
without that capability throws. The application state and resource pool remain
shared with the primary tree.
AuxiliaryPortal
function AuxiliaryPortal(props: AuxiliarySurfaceProps): JSX.ElementRenders children into the auxiliary display's overlay layer. Use it for
content that must paint above the rest of <AuxiliarySurface>; ordinary
Portal always targets the primary display.
Modal
interface ModalProps {
class?: string;
panelClass?: string;
open?: boolean | (() => boolean);
children?: JSX.Element;
}
function Modal(props: ModalProps): JSX.ElementA portalled backdrop + focus-scoped panel. While open, it blocks background button handlers (pushButtonHandlerBlock) and fades/scales the panel in. class styles the centering frame; panelClass styles the panel.
Named
function Named(props: { name: string; children?: JSX.Element }): JSX.ElementTags the host nodes it renders with a semantic name for the
DevTools component tree (<Named name="MessageCard"><Card/></Named>).
Renders no node of its own; a child's explicit debugName prop wins.
ActionBar
function ActionBar(props: ActionBarProps): JSX.Element // ActionBarProps extends ViewPropsA portalled bottom bar. Defaults to a pinned left-3 right-3 bottom-3 row when no class is given.
Grid
interface GridProps extends ViewProps, Partial<FocusGridOptions> {
gap?: number; // cross-axis gap px (via style)
active?: boolean | (() => boolean); // enable FocusGrid traversal (needs columns)
}
function Grid(props: GridProps): JSX.ElementA wrapping tile layout (flex-row flex-wrap). With columns + active it delegates row/column d-pad traversal to FocusGrid; columns drives traversal only — layout stays flexbox. gap is a number so class can stay a single compiled literal.
Lazy
interface LazyProps {
when: boolean | (() => boolean); // mount while truthy; destroy when false
reveal?: number; // host frames to show fallback first (0)
fallback?: JSX.Element | (() => JSX.Element);
children: () => JSX.Element; // deferred content factory
}
function Lazy(props: LazyProps): JSX.ElementOn-demand mount: builds children only while when is truthy (the sweep destroys the subtree when it goes false). reveal shows fallback for N frames the first time it activates, then latches revealed for its lifetime (no replay). Models on-demand content build — textures are still uploaded eagerly at pak load.
Gallery
interface GalleryProps {
count: number; // total pages
page: () => number; // controlled current-page accessor
onPageChange?: (next: number) => void;
renderPage: (index: number) => JSX.Element; // called only for in-window pages
window?: number; // pages kept mounted each side (1)
duration?: number; // slide ms (300)
easing?: EasingName; // slide easing ("out")
bindTriggers?: boolean; // bind LTRIGGER/RTRIGGER (true)
wrap?: boolean; // wrap past the ends (false)
class?: string; // outer viewport class
}
function Gallery(props: GalleryProps): JSX.ElementA full-screen L/R-paged strip: LTRIGGER/RTRIGGER slide one whole screen at a time. Controlled (page + onPageChange); the slide is one native translateX tween per press (paint-only), and pages outside window are not built, keeping many-page galleries inside the draw budget. See apps/gallery.
DeepZoom (Solid)
function DeepZoom(props: DeepZoomProps): JSX.ElementA streamed tiled-canvas viewer. It selects from a baked TileDoc pyramid,
keeps an overview beneath the active level, loads a bounded number of tiles per
frame, and releases generation-tagged texture handles outside the viewport.
D-pad/left-analog panning and trigger zoom are built in; gestureSource can
supply logical-coordinate pan/pinch gestures with an anchored zoom point.
| Prop | Type | Description |
|---|---|---|
doc |
TileDoc |
Baked document dimensions, background, tile edge, and resolution levels. |
width / height |
number |
Logical viewport size (defaults to 480×272). |
loadBudget |
number |
Maximum textured-tile uploads per frame (default 2). |
prefetch |
number |
Extra mounted tile ring (default 1). |
bindInput |
boolean |
Bind controller pan/zoom internally (default true). |
gestureSource |
() => DeepZoomGesture | null |
Optional direct-manipulation input for touch hosts. |
onView |
(view: DeepZoomView) => void |
Observe deterministic center, zoom, and selected level. |
DeepZoom is currently exported by the Solid components adapter. The tile
wire format and texture-streaming HostOps remain framework-neutral.
useViewport (Solid)
interface ViewportSize { w: number; h: number }
function useViewport(): Accessor<ViewportSize>The logical viewport as a signal, in logical pixels. The first value is the
size the host published at mount (ui.__viewport), or the spec screen
(480×272) on a host that publishes none. Each resizeViewport sets the next
value; a resize to the same size does not notify. The subscription ends with
the owner that called the hook.
A component reads it to pick a layout from the width: the number of columns in a grid, or whether two panels sit in a row or in a column.
const viewport = useViewport();
const columns = () => Math.max(1, Math.min(4, Math.floor((viewport().w - 48 + 16) / (240 + 16))));
const card = () => (Math.min(1124, viewport().w - 48) - (columns() - 1) * 16) / columns();
<For each={games()}>{(g) => <View style={{ width: card() }}>…</View>}</For>The size changes only on targets with display.viewport.live (windows and
widgets). An app that declares the capability and a dynamic viewport variant
gets every window size inside the declared min…max range.
solid-js
Import Solid's reactive primitives and control-flow components directly from
solid-js. PocketJS relies on the real Solid runtime rather than wrapping or
curating these exports. Full docs live at
solidjs.com; summary below.
Reactivity
| Export | Signature | Purpose |
|---|---|---|
createSignal |
createSignal<T>(value?, opts?) => [get: () => T, set: (v) => T] |
Reactive atom. |
createEffect |
createEffect(fn: (prev) => T, value?) => void |
Run on dependency change. |
createMemo |
createMemo(fn: (prev) => T, value?) => () => T |
Cached derived value. |
onMount |
onMount(fn: () => void) => void |
Run once after first render. |
onCleanup |
onCleanup(fn: () => void) => void |
Run on owner disposal. |
batch |
batch(fn: () => T) => T |
Coalesce updates. |
untrack |
untrack(fn: () => T) => T |
Read without tracking. |
See Reactivity.
Control flow
| Component | Usage | Purpose |
|---|---|---|
Show |
<Show when={cond} fallback={…}>…</Show> |
Conditional render. |
For |
<For each={list}>{(item, i) => …}</For> |
List keyed by reference. |
Index |
<Index each={list}>{(item, i) => …}</Index> |
List keyed by index. |
Switch / Match |
<Switch fallback={…}><Match when={c}>…</Match></Switch> |
Multi-branch. |
PocketJS's renderer maps these updates onto the native tree, but the component APIs and semantics are Solid's.
vue
Vue Vapor apps import Vue's Composition API directly from vue; PocketJS does
not wrap refs, computed values, effects, or component definitions. Use
@pocketjs/framework/vue-vapor/components explicitly, or set
framework: "vue-vapor" and import generic @pocketjs/framework/components.
octane
Octane apps import React-model hooks directly from octane (useState,
useEffect, useMemo, useRef, useLayoutEffect, useEffectEvent, …);
PocketJS does not wrap them. Dependency arrays may be omitted — the Octane
compiler infers them from captures — and hooks are tracked by call site
(conditional hooks in if blocks are fine, hooks in loops are not). Use
@pocketjs/framework/octane/components explicitly, or set
framework: "octane" and import generic @pocketjs/framework/components.
PocketJS's per-frame lifecycle hooks are use-prefixed in Octane builds —
useFrame, useButtonPress, and useSpriteAnimation from
@pocketjs/framework/octane/lifecycle — because the Octane compiler slot-keys
custom hooks by the use[A-Z] naming convention. Their signatures match
onFrame / onButtonPress / createSpriteAnimation below, except
useSpriteAnimation returns the current frame key as a plain string.
pushButtonHandlerBlock is not a hook and keeps its name.
@pocketjs/framework/animation
Typed motion over ops.animate. JS declares the tween once; the Rust core
advances it one fixed tick at a time, dt = 1 / tick rate for the rate the
bundle bakes (see clock). prop is a spec PROP name and must
be animatable (e.g. opacity, translateY, scale, and color props) —
non-animatable props throw. See Animation.
animate
function animate(
node: NodeMirror | number,
prop: PropName,
to: number | string,
opts?: AnimateOptions,
): number // returns animIdTweens prop from its current value to to. For color props, to is a packed u32 ABGR or a '#rrggbb' / '#rrggbbaa' string. Returns an animId for cancelAnim.
AnimateOptions
| Field | Type | Default | Description |
|---|---|---|---|
dur |
number |
200 |
Duration in ms (ignored by spring easings). |
easing |
EasingName | number |
"out" |
Named easing or raw ENUMS.Easing ordinal. |
delay |
number |
0 |
Delay in ms before the tween starts. |
EasingName — "linear" | "in" | "out" | "in-out" | "out-back" | "spring" | "spring-bouncy".
jump
function jump(node: NodeMirror | number, prop: PropName, value: number | string): voidSets an animatable prop for this frame with no tween. A jump on a transform
prop is paint-only — one setProp, no relayout — which is what a finger-follow
drag writes on every move frame.
spring
function spring(
node: NodeMirror | number,
prop: PropName,
to: number | string,
preset?: "default" | "bouncy",
): numberSprings prop to to; duration comes from the physics, not a timer. preset (default "default") selects the base or bouncy spring. Returns an animId.
cancelAnim
function cancelAnim(animId: number): voidStops a running animation by the id animate/spring returned.
animationClass
const animationClass: "composited" | "repaint" | "still";What a changed frame costs the target this bundle was compiled for, from
the plan (see Platform contracts).
composited is a GPU; repaint is a CPU that pays per repainted pixel and
moves translated opaque regions; still is electronic paper, where
animate and spring set the end value and return 0. A bundle built
without a plan reads composited.
@pocketjs/framework/lifecycle
Component-scoped per-frame hooks. Registrations clean up with the selected
framework owner (onCleanup in Solid, onScopeDispose in Vue Vapor, effect
cleanup in Octane). In Octane builds these exports are the use-prefixed hooks
useFrame, useButtonPress, and useSpriteAnimation (see
octane above); the signatures below are otherwise identical. See
Reactivity and Input & focus.
onFrame
function onFrame(callback: (buttons: number) => void): voidRegisters callback to run once per host frame with the current spec BTN bitmask.
Analog input
function analogX(): number
function analogY(): number
function analogRaw(): numberanalogX and analogY return the current left stick/nub axis in -1..1
after PocketJS's shared deadzone (right and down are positive).
analogRaw returns the host word (x << 8) | y, with each byte in 0..255
and 128 at center. Stickless hosts stay centered, so controller fallbacks do
not need target checks. Solid, Vue Vapor, and Octane expose the same functions
from their lifecycle subpaths.
onButtonPress
function onButtonPress(
mask: number,
callback: (pressed: number, buttons: number) => void,
opts?: ButtonPressOptions,
): voidEdge-detects a button: fires callback on the frame a button in mask transitions from up to down. pressed is the just-pressed bitmask; buttons is the full held mask.
ButtonPressOptions
| Field | Type | Default | Description |
|---|---|---|---|
allowWhenBlocked |
boolean |
false |
Keep firing while a modal/system block owns input. |
active |
boolean | (() => boolean) |
true |
Gate the handler on/off. |
latched |
boolean |
false |
Require the button to be observed released before the next edge can fire; prevents a held opener from re-triggering a newly mounted screen. |
createSpriteAnimation
function createSpriteAnimation(
frames: readonly string[],
opts?: SpriteAnimationOptions,
): Accessor<string> | ComputedRef<string>Cycles through frames (image src keys), returning a Solid Accessor or a
Vue Vapor ComputedRef for the current frame (the Octane hook,
useSpriteAnimation, returns the current frame key as a plain string).
Throws if frames is empty.
opts.frameStep (default 1, min 1) holds each sprite frame for that many
host frames.
pushButtonHandlerBlock
function pushButtonHandlerBlock(): () => voidPushes a global block so background onButtonPress handlers (those without allowWhenBlocked) stop firing; the returned disposer pops it. Modal uses this internally.
@pocketjs/framework/input
Programmatic focus, the button bitmask, the touch snapshots, the virtual
cursor, and the imperative focus-scope/grid/controller stack. Prefer the
FocusScope / FocusGrid components in app code. The behavior these
signatures produce — the traversal order, the press and bubble model, refocus
on removal — is on Input & focus.
BTN
PSP button bitmask (identical on every host; web/Bun hosts remap keys).
| Member | Value | Member | Value |
|---|---|---|---|
SELECT |
0x0001 |
LTRIGGER |
0x0100 |
START |
0x0008 |
RTRIGGER |
0x0200 |
UP |
0x0010 |
TRIANGLE |
0x1000 |
RIGHT |
0x0020 |
CIRCLE |
0x2000 |
DOWN |
0x0040 |
CROSS |
0x4000 |
LEFT |
0x0080 |
SQUARE |
0x8000 |
touches and auxiliaryTouches
interface TouchContact {
readonly id: number;
readonly x: number;
readonly y: number;
readonly surface: "primary" | "auxiliary";
readonly hit?: number;
}
function touches(): readonly TouchContact[]
function auxiliaryTouches(): readonly TouchContact[]Each function returns an immutable snapshot for one surface. Coordinates are
logical pixels in that surface, independent of the target raster density; at
most eight contacts are delivered across both snapshots. A host that sends
exact positions gives fractional coordinates and coordinates past 1023;
otherwise they are whole pixels from 0 to 1023. No active touch is an
empty snapshot, not an unavailable API. Declare input.touch for touches()
or input.touch.auxiliary plus display.auxiliary for
auxiliaryTouches(). Guard optional enhancements with hasFeature().
| Field | Type | Description |
|---|---|---|
id |
number |
Stable while the contact stays down; ids are reused after a release. |
x / y |
number |
Logical viewport position in this surface. |
surface |
"primary" | "auxiliary" |
Which output's coordinate space the contact belongs to. |
hit |
number | undefined |
Down-edge hit fact: the node id the host bounds-resolved under the contact when it landed, carried unchanged until the contact lifts. |
hit is 0 when the host resolved the position and no node claimed it (a
contact on bare background, or off-screen edge cases), and undefined when
the host has no hit-fact channel at all — an older host, or a DevTools replay.
Hosts derive the fact from the bounds hit test; see
Native contract for the ops and the frame()
argument that carries them.
pointer and onScroll
interface PointerState {
readonly surface: "primary" | "auxiliary";
readonly x: number;
readonly y: number;
readonly buttons: number;
}
interface ScrollEvent {
readonly surface: "primary" | "auxiliary";
readonly x: number;
readonly y: number;
readonly dx: number;
readonly dy: number;
}
function pointer(): PointerState | null
function onScroll(handler: (event: ScrollEvent) => boolean | void): () => voidpointer() returns the frame's pointer, with or without a button down, or
null when the host reports none. Coordinates are unclamped logical pixels of
surface; bit 0 of buttons is the primary button. onScroll receives the
frame's summed wheel and trackpad scrolling in logical pixels at the pointer's
position; positive dy moves the view toward the content's end. Handlers run
newest first, a true return consumes the event, and the returned function
removes the handler. Declare input.pointer for pointer() and
input.scroll, which requires input.pointer, for onScroll. In a build
whose plan turns input.scroll off, onScroll keeps no handler and returns
a function that does nothing. See
Input & focus.
focusNode
function focusNode(node: NodeMirror | null): voidProgrammatically focus a node (or clear focus with null). Applies the native focus: style variant.
getFocused
function getFocused(): NodeMirror | nullReturns the currently focused node, or null.
pushFocusScope
function pushFocusScope(node: NodeMirror, opts?: FocusScopeOptions): () => voidRestricts d-pad traversal and CIRCLE to node's subtree; returns a disposer that pops the scope and restores prior focus. Backs the FocusScope component.
FocusScopeOptions
| Field | Type | Default | Description |
|---|---|---|---|
autoFocus |
boolean |
true |
Focus the first focusable on push. |
restoreFocus |
boolean |
true |
Restore the previously focused node on pop. |
pushFocusGrid
function pushFocusGrid(node: NodeMirror, opts: FocusGridOptions): () => voidGives node's subtree row/column d-pad semantics; returns a disposer that pops the grid. Backs the FocusGrid component.
FocusGridOptions
| Field | Type | Default | Description |
|---|---|---|---|
columns |
number |
— | Grid column count (min 1). Required. |
wrap |
boolean |
false |
Wrap focus at row ends. |
Virtual cursor
function enableCursor(opts?: CursorOptions): () => void
function cursorX(): number
function cursorY(): numberenableCursor replaces the d-pad focus walk with a pointer the analog nub
steers, and returns a disposer that restores the d-pad model. Calling it again
while enabled updates the options in place, and an unchanged image keeps the
texture it uploaded. A host predating the cursor ops keeps the d-pad model.
cursorX / cursorY read the position in logical px, NaN while the cursor
is disabled or before its first frame. List input.cursor in the
application's features. What changes on screen while it runs — hover as focus, the
press-and-drag-off model, the suppressed d-pad traversal — is on
Input & focus.
CursorOptions
| Field | Type | Default | Description |
|---|---|---|---|
image |
string | Uint8Array |
built-in 16×16 arrow | A pak IMG entry key, or a raw IMG entry blob. |
hotspot |
[number, number] |
[0, 0] |
The sprite pixel the position points at. |
size |
[number, number] |
the texture's own size | Logical draw size. |
speed |
number |
240 |
Travel in px per virtual second at full nub deflection, so a tape replays the same path at every rate: 240 is 4 px per frame on a 60 Hz bundle. |
dpadSpeed |
number |
0 |
Steer with the d-pad at this px per virtual second while the nub is centered; 0 leaves the d-pad to the app. |
button |
number |
BTN.CIRCLE |
Mask that presses the hovered node. |
start |
[number, number] |
viewport center | Initial position. |
Hit testing and programmatic activation
function pressNode(node: NodeMirror): void
function setActiveNode(node: NodeMirror | null): void
function pushFocusController(
node: NodeMirror,
move: (direction: FocusDirection) => boolean,
): () => void
function hitFocusable(x: number, y: number): NodeMirror | null
function hitNode(x: number, y: number, surface?: "primary" | "auxiliary"): NodeMirror | nullpressNode focuses a node and fires its onPress, bubbling to the nearest
ancestor handler — the path a touch tap and a cursor click both take.
setActiveNode holds or clears the native active: variant through the one
latch every input mode writes, so a pressed look cannot strand when the mode
changes. pushFocusController gives a subtree custom d-pad traversal: while
focus is inside node, each navigation press calls move instead of grid or
linear traversal and a false return falls through to the default; the system
keyboard drives its variable-width key rows this way. hitFocusable resolves
a point to the nearest focusable inside the active focus scope — the filter
cursor hover and touch activation share. hitNode returns the topmost painted
node under a point with no focusable or scope filter, which is how the gesture
layer resolves region ownership. Both return null where the host mounts no
hitTest op.
@pocketjs/framework/gesture
Recognizers over the per-frame touch snapshot: tap, long press, axis-lockable
pan, and two-contact pinch, plus the ownership model that decides which
recognizer keeps a contact when several want it. The recognizer machinery is
framework-neutral; Solid and Vue Vapor resolve their own createGesture
shim over it, and Octane builds do not resolve this subpath. The pump runs
once per frame from the framework entry, after effect delivery and before app
frame hooks, so app code always reads this frame's completed output. On a host
that delivers no contacts the recognizers never fire and cost nothing. See
Touch & gestures.
createGesture and attachGesture
function createGesture(opts: GestureOptions): GestureHandle
function attachGesture(opts: GestureOptions): GestureHandleattachGesture registers a recognizer and returns its handle; it stays
registered until the caller calls handle.dispose(). createGesture makes the
same registration and hands disposal to the surrounding component scope —
onCleanup in Solid, onScopeDispose in Vue Vapor — so the recognizer
unregisters with the component that created it. Use createGesture inside
components and attachGesture when there is no component scope to own it.
GestureOptions
| Field | Type | Default | Description |
|---|---|---|---|
surface |
"primary" | "auxiliary" |
"primary" |
Output to observe. A recognizer only sees contacts on this surface. |
region |
GestureRegion |
— | Where the recognizer takes ownership. Omit for a whole-screen recognizer. |
axis |
"x" | "y" | "any" |
"any" |
Pan axis lock, and the axis a pinch measures its span on. |
tapSlop |
number |
8 |
Max total travel per axis, logical px, for the contact to count as a tap. |
panSlop |
number |
6 |
Total travel, logical px, that starts a pan. |
pinchSlop |
number |
10 |
Span change, logical px, that starts a pinch. |
longPressSeconds |
number |
0.5 |
Hold duration in virtual seconds. The deadline is max(1, round(longPressSeconds × simulationHz())) virtual frames, so it holds the same wall time at every rate. |
allowWhenBlocked |
boolean |
false |
Keep observing while a pushTouchBlock is held. |
onDown |
(c: GestureContact) => void |
— | Contact landed inside the region. |
onMove |
(c: GestureContact) => void |
— | Contact moved this frame, panning or not. |
onUp |
(c: GestureContact) => void |
— | Contact released. |
onCancel |
(c: GestureContact) => void |
— | Another owner claimed the contact, a touch block was pushed, or the handle was disposed or cancelled. |
onTap |
(c: GestureContact) => void |
— | Released within tapSlop with nothing claimed and no long press fired. |
onLongPress |
(c: GestureContact) => void |
— | Held past the deadline within tapSlop. Fires once, then claims. |
onPanStart |
(c: GestureContact) => void |
— | Travel crossed panSlop on the locked axis. Claims the contact. |
onPanMove |
(c: GestureContact) => void |
— | Every frame while panning, including hold frames where fdx/fdy are 0. |
onPanEnd |
(c: GestureContact) => void |
— | Released while panning; c.vx/c.vy is the fling velocity. |
onPinchStart |
(p: GesturePinch) => void |
— | Span change beat pinchSlop and dominated the centroid's travel. Claims both members. |
onPinchMove |
(p: GesturePinch) => void |
— | Every frame while pinching, including hold frames where fdspan is 0. |
onPinchEnd |
(p: GesturePinch) => void |
— | A member released, was cancelled, or the handle was disposed; p carries the final geometry. |
An axis lock rejects cross-axis movement rather than killing the contact:
while the recognizer is unclaimed the axis test is re-evaluated every frame, so
a thumb that lands with wobble still pans once its intended axis dominates, and
a drag whose dominant axis never matches never pans on that recognizer.
A pan and a pinch on the same recognizer both need handlers to run: the pan
pass skips a recognizer with no onPanStart/onPanMove/onPanEnd, and the
pinch pass skips one with no onPinchStart/onPinchMove/onPinchEnd.
GestureContact
| Field | Type | Description |
|---|---|---|
surface |
"primary" | "auxiliary" |
Output whose coordinate space holds this contact. |
id |
number |
Stable while the contact is down; ids are reused after a release. |
x / y |
number |
Current position, logical viewport px. |
startX / startY |
number |
Position at the down edge. |
dx / dy |
number |
Total travel since the down edge. |
fdx / fdy |
number |
Travel this frame — what a finger-follow drag consumes. |
vx / vy |
number |
Velocity in logical px per virtual second, estimated over a 3-frame window; on the release frame this is the fling velocity. |
downFrame |
number |
virtualFrame() at the down edge. |
frames |
number |
Frames since the down edge (0 on the down frame). |
hit |
number | undefined |
The down edge's TouchContact.hit fact, carried for the contact's lifetime. |
Velocity is an integer position delta over k fixed-length frames with one
IEEE division per axis, so the same contact path produces the same number on
every host.
GesturePinch
| Field | Type | Description |
|---|---|---|
ax / ay |
number |
First member's current position, logical viewport px. |
bx / by |
number |
Second member's current position. |
cx / cy |
number |
Centroid of the two members. |
span |
number |
Distance between the members, projected onto the recognizer's locked axis; Euclidean when axis is "any". |
startSpan |
number |
The span when the pair formed, before the slop was crossed. |
dspan |
number |
span - startSpan; positive when the members moved apart. |
fdspan |
number |
Span change this frame — what an opening gap consumes. |
GestureRegion
| Field | Type | Description |
|---|---|---|
node |
() => NodeMirror | null | undefined |
Own contacts whose down-edge hit lands inside this node's subtree. |
rect |
() => { x, y, w, h } | null | undefined |
Logical-px geometry: the fallback when the hit misses, and the whole test when no node is given. |
Both are getters, read at the down edge. Returning null from the getter (or
supplying neither) means the recognizer owns nothing that frame, which is how
a recognizer is switched off without disposing it.
The down edge is resolved once and shared across every recognizer: the host's
hit fact is used when the frame carried one, otherwise a single query through
hitTestBounds when the host has it and hitTest otherwise. A resolution that
lands outside the subtree fails the match and never falls through
to rect — ink painted above the region occludes it. A resolution that hits
nothing falls through to rect, so gaps between rows still reach a list's pan
recognizer.
GestureHandle
| Member | Type | Description |
|---|---|---|
dispose() |
() => void |
Cancel in-flight contacts, end an in-flight pinch, and unregister. |
cancel() |
() => void |
Force-cancel this recognizer's in-flight contacts (fires onCancel) without unregistering. |
panning |
boolean |
True while any contact is mid-pan under this recognizer. |
pinching |
boolean |
True while a pinch is in flight under this recognizer. |
pushTouchBlock
function pushTouchBlock(): () => voidThe touch mirror of pushButtonHandlerBlock.
Pushing cancels the in-flight contacts of every recognizer without
allowWhenBlocked inside the call, so those owners see onCancel on this
frame rather than a release later, and suppresses new downs for them while
the block is held; the returned disposer pops it. Recognizers with
allowWhenBlocked keep observing. Blocks nest, and the depth only reaches zero when every
disposer has run. The system keyboard pushes one for its own panel; Modal
pushes the button block only.
Ownership
These rules decide which recognizer keeps a contact when several observe it.
- Owners are resolved at the down edge. Every non-disposed recognizer whose
surfaceandregionmatch the contact becomes an owner and observesonDown,onMoveandonUp. - Priority is registration order, last registered first. Mount order is deterministic, so priority is too. A component registering a richer touch model after mount outranks anything registered before it.
- A claim cancels every other owner. A pan crossing
panSlop, a long press firing, or a pinch forming claims the contact for that recognizer, and every other owner of that contact receivesonCancel. A pinch claims both its members at once. - Cancellation is terminal for that contact. A cancelled recognizer
observes nothing further from it — no
onMove, noonUp, noonTap— until the contact lifts and a new one lands. - Tap and long press single-fire. Each resolves on the highest-priority
owner that carries the handler, and no lower-priority owner sees it. Tap
death is per-owner: each recognizer applies its own
tapSlop. - The pinch pass runs before the pan pass. Two diverging contacts become a pinch even when each alone would satisfy a pan. Two contacts travelling together, with the span steady and the centroid moving, stay available to the pan recognizers. The pair a recognizer measures is the first two unclaimed contacts it still observes.
- Contact and pinch objects are pooled and mutable. They are valid only for the duration of the callback. Never retain one across frames or store it in state; copy the numbers you need.
@pocketjs/framework/kinetics
A one-axis kinetic scroller: finger-follow tracking with a rubber-banded
overscroll, an exponential-decay fling, an edge spring that carries the
incoming velocity, a per-frame chase for d-pad and stick-to-bottom scrolling,
and a programmatic tween. The state machine is framework-neutral; the Solid
shim binds the offset to a signal and the Vue Vapor shim to a shallowRef, and
Octane builds do not resolve this subpath. See
Touch & gestures.
The physics are fixed platform literals, not app knobs: the decay rates
(0.998/ms and 0.99/ms, pre-baked per tick), the 0.55 rubber-band
coefficient, the K = 170 / C = 26 edge spring, and the chase pump's 0.3
rate all live in the module. Fling and spring integrate per core tick, so a
30 Hz host follows the 60 Hz trajectory subsampled; chase advances once per
frame by design. Every formula is + − * / over literals, so trajectories are
bit-identical on every host.
createScroller
function createScroller(opts: ScrollerOptions): ScrollerCreates a scroller whose offset is a reactive cell of the active framework.
Bind translateY: -s.offset() on the content canvas — a translate is
paint-only, one setProp per moving frame with no relayout — and call
s.step() once per frame from onFrame. Nothing advances without that pump.
ScrollerOptions
| Field | Type | Default | Description |
|---|---|---|---|
max |
() => number |
— | Range end; for a list that scrolls its content, max(0, contentH - viewH). Read on every step, so a growing list needs no re-registration. Required. |
extent |
() => number |
screen height | Viewport extent, which is the rubber band's asymptote. |
initial |
number |
0 |
Starting offset. |
overscroll |
number |
48 |
Cap on rubber-band travel in px; 0 hard-clamps at the edges. |
decay |
"normal" | "fast" |
"normal" |
Fling decay preset: "normal" is the iOS 0.998/ms rate, "fast" the 0.99/ms paging rate. |
snap |
((projectedRest: number, velocity: number) => number) | null |
null |
Applied at endDrag instead of a fling: receives the projected rest position and the release velocity, returns the position to tween to. This is how paging and row alignment are built. |
onSettle |
(offset: number) => void |
— | A moving state reached rest. The settled offset is rounded to 1/64 px so settled framebuffers hash to the same value. |
ScrollerState
type ScrollerState = "idle" | "tracking" | "fling" | "spring" | "chase" | "tween"tracking is finger-follow, fling the decay from a release velocity,
spring the edge bounce-back (entered mid-fling when a fling crosses an edge,
carrying its momentum), chase the per-frame ease toward a target, tween a
programmatic scrollTo, and idle at rest.
Scroller
| Member | Signature | Description |
|---|---|---|
offset |
() => number |
Current offset in logical px. Reactive. |
velocity |
() => number |
Instantaneous velocity in px per virtual second; meaningful in fling and spring. |
state |
() => ScrollerState |
The current state. |
beginDrag |
() => void |
Enter finger-follow. Wire to a pan start. |
drag |
(deltaPx: number) => void |
Content-space delta for this frame; a vertical list passes -c.fdy. |
endDrag |
(releaseVelocity: number) => void |
Release; a vertical list passes -c.vy. Decides between fling, edge spring, snap, and settling in place. |
scrollTo |
(to: number, opts?: { durMs?: number } | { immediate: true }) => void |
Programmatic scroll, tweening over 200 ms by default. |
scrollBy |
(delta: number, opts?: { durMs?: number } | { immediate: true }) => void |
Same, relative to the in-flight target when one exists. |
stop |
() => void |
Freeze in place. No settle callback. |
nudge |
(delta: number) => void |
Move the chase target by a delta — the d-pad and analog primitive. |
chaseTo |
(to: number) => void |
Chase an absolute target (focus-follow, stick-to-bottom). |
rebase |
(delta: number) => void |
Shift the offset and every in-flight anchor by delta. |
intent |
() => number |
Where the scroller is heading: the chase or tween target when one is in flight, the current offset otherwise. |
isAtEnd |
(slackPx?: number) => boolean |
Whether the range end is reached, judged on intent() rather than the current position. slackPx defaults to 1. |
projectFling |
(v: number) => number |
Rest position a fling from v would reach. Use it inside a snap function. |
step |
() => void |
Advance one frame. Call once per frame from onFrame. |
rebase exists for prepends. Shifting only the offset would leave a drag
position, a chase target, a spring bound, or a tween's endpoints pointing at
pre-prepend coordinates; rebase moves all of them together, so backfilling
content above the viewport never moves what the reader is looking at, even
mid-fling.
bindDpadScroll
function bindDpadScroll(s: Scroller, opts?: DpadScrollOptions): voidRegisters an onFrame hook that turns held UP/DOWN and the analog stick into
nudge calls against the scroller's chase target. The caller still owns
step().
| Field | Type | Default | Description |
|---|---|---|---|
stepPx |
number |
6 |
Px per held frame of UP/DOWN. |
nubPx |
number |
10 |
Px per frame at full analog deflection. |
active |
() => boolean |
always on | Gate the hook, for example () => !osk.isOpen(). Raw button reads are not muted by a touch or button block. |
@pocketjs/framework/platform
const platform: {
readonly target: string;
readonly pixelRatio: number;
readonly features: Readonly<Partial<Record<FeatureId, boolean>>>;
};
function hasFeature(feature: FeatureId): boolean
// A registered id, which editors complete, or an id the host contract defines.
type FeatureId = PocketCapabilityId | (string & {});For a bundle built from a build plan, tools/build.ts defines the
target-specific constants consumed by this module from the plan.
pixelRatio is physical raster samples per logical pixel (1 on PSP, 2 on Vita), useful for
runtime-created textures; it never changes layout coordinates. Literal
hasFeature("…") calls are folded to booleans during the PocketJS compile, so
an unavailable enhancement branch can leave the bundle. Computed ids use the
frozen runtime map.
@pocketjs/framework/modality
const modality: Modality;
const presentation: string;
function screen(role?: "primary" | "auxiliary"): ScreenModality | undefined
function surfaceHasTouch(surface?: "primary" | "auxiliary"): boolean
function supports(requirement: ModalityRequirement): boolean
function glyph(button: "circle" | "cross" | "triangle" | "square" | "start" | "select" | "ltrigger" | "rtrigger"): stringmodality is the target's interaction structure the plan resolved
(screens, touch, pointer, buttons, analog, text, glyphs,
form; see Platform contracts),
frozen. presentation is the plan's presentation id, "default" for a plan
resolved from a host config. screen("auxiliary") is undefined on a
single-screen target. supports() evaluates a ModalityRequirement
(contracts/spec/modality.ts) against modality. glyph("circle") is "○" on a
PSP or Vita and "A" on a 3DS, so hint text names the button the shell prints. A bundle built without a
plan reads the portable PSP modality.
@pocketjs/framework/actions
function useActions(actions: ActionMap | (() => ActionMap), options?: { allowWhenBlocked?: boolean }): {
legend: () => string;
entries: () => readonly ActionEntry[];
run(intent: ActionIntent): void;
}ActionMap maps intents (confirm, back, action, option,
sectionPrev, sectionNext, media) to { label?, run?, hold?, when? }.
On a device with buttons each intent is bound to one face button
(ACTION_BUTTONS: ○ × △ □ L R START) for the component's lifetime, and
legend() spells the labelled intents with the device's glyphs, so one
declaration renders ○ play · △ search on a PSP and A play · X search on a
3DS. An intent with a label and no run appears in the legend while the
focus system delivers the press. hold fires after HOLD_SECONDS of holding
the button and silences the tap. Bindings respect the button-handler block a
keyboard or sheet pushes. On a device without buttons legend() is empty and
nothing binds; entries() still lists the intents for touch controls.
@pocketjs/framework/classic
The bezelled light chrome every classic presentation shares (docs/HIG.md):
ClassicBar (36 px title bar with title, trailing text and absolute
children), ClassicFooter (24 px legend strip), ClassicList (a
VirtualList with flush rows, the ClassicSelection wash on the focused
row, a trailing loading row that requests the next page for the d-pad and
for a scrolling finger, and a per-frame onWindow(first, visible, velocity)
report for row prefetching), ClassicSelection, ClassicSpinner (eight bars,
no textures), ClassicSkeleton, ClassicButton, ClassicFace,
ClassicPanel, ClassicSheet, and the CLASSIC color tokens.
@pocketjs/framework/clock
| Export | Purpose |
|---|---|
simulationHz() |
Active virtual-frame rate selected by the host. |
ticksPerFrame() |
Exact core ticks advanced per virtual frame. |
virtualFrame() |
Deterministic frame index. |
virtualNow() |
Virtual seconds since boot. |
after(seconds, callback) |
Schedule on the virtual clock; returns a disposer. |
Use these instead of wall-clock timers for deterministic app behavior: the same elapsed virtual time produces the same trajectory at every rate.
The tick rate is declared per realm and baked per bundle, not fixed at 60.
An application states it as app.tickHz (1 through 60, default 60) and the
plan carries it as profile.tickHz; tools/build.ts writes it in from the plan
or from --hz=N — an integer from 1 through 240, default 60 — and the core
takes it through set_tick_rate before the first tick (MAX_TICK_HZ is 240 in
engine/core/src/lib.rs). A device publishes its cadence as __simHz. simulationHz() is
the host-selected virtual-frame rate and is a divisor of the baked rate, which
is what makes ticksPerFrame() a whole number. A native mount whose
ui.__tickHz disagrees with the baked rate throws before anything renders
(assertNativeHostContract, framework/src/host.ts): a bundle runs at the
rate it was built for and no other.
@pocketjs/framework/effects
type EffectDriver = (command: EffectCommand, deliver: (result: unknown) => void) => void;
function installEffectDriver(driver: EffectDriver): void
function runEffect<T>(kind: string, payload: unknown, onResult: (result: T) => void): numberrunEffect emits an outside-world command; its driver can complete at any
time, but PocketJS delivers the result only at the next frame boundary. This
callback surface keeps promise and microtask timing out of deterministic
journeys. A host-injected globalThis.__pocketEffectDriver overrides the app
driver for replay and simulation.
@pocketjs/framework/fs
Files in the Bun shape — file(path) plus the node:fs sync subset Bun
implements — over the nine-op fs spec (read, write, remove, list,
stat, mkdir, rename, usage, lastError). Every call is synchronous,
and await on a plain value unwraps it, so await file(p).text() and
await write(p, data) both run here.
import { file, write, readdirSync } from "@pocketjs/framework/fs";
write("saves/slot1.json", JSON.stringify(state));
if (file("saves/slot1.json").exists()) restore(file("saves/slot1.json").json());
for (const name of readdirSync("saves")) console.log(name);| Export | Signature | Description |
|---|---|---|
file |
(path: string) => PocketFile |
A lazy handle; nothing is read until a method runs. |
PocketFile |
.size, .exists(), .bytes(), .text(), .json(), .delete() |
size is 0 for a missing file (Bun's behavior); exists() is true only for a file. |
write |
(path, data: string | Uint8Array) => number |
Replace the file, creating parent directories. Returns bytes written. |
usage |
() => { usedBytes: number; quotaBytes: number } |
The app's storage footprint and budget; quotaBytes: 0 is unmetered. |
readFileSync |
(path, encoding?: "utf8") => Uint8Array | string |
Bytes, or a string with "utf8". |
writeFileSync / appendFileSync |
(path, data) => void |
Truncating and appending writes. |
mkdirSync |
(path) => void |
Recursive and idempotent: every missing ancestor is created. |
readdirSync |
(path, options?: { withFileTypes: true }) => string[] | DirEntry[] |
Names, or { name, kind, size, isFile(), isDirectory() } entries. |
rmSync |
(path, options?: { recursive?: boolean; force?: boolean }) => void |
recursive removes a tree; force swallows "not found". |
renameSync |
(from, to) => void |
Move within the data root. |
statSync |
(path) => { size, isFile(), isDirectory() } |
Throws where the path does not exist. |
existsSync |
(path) => boolean |
True for a file or a directory. |
A path carries at most FS_MAX_DEPTH (8) segments, 64 bytes per segment and
160 bytes in total. The SDK chunks reads and writes at FS_MAX_IO_BYTES
(64 KiB), so a file's size is bounded by storage and any host quota rather
than by the marshaling ceiling.
@pocketjs/framework/audio
Streams s16 PCM to the host's audio namespace on a credit budget. List
audio.pcm in the application's features. Where no host mounts the module every player
call is a no-op and the app's tick-driven UI stays byte-identical, so an audio
enhancement needs no branch around it.
import { createWavPlayer } from "@pocketjs/framework/audio";
import { onFrame } from "@pocketjs/framework/lifecycle";
const player = createWavPlayer();
player.load("theme"); // the pak entry audio:wav.theme
player.play();
onFrame(() => player.pump());pump() must be called once per frame from the app's onFrame. It drains
the tick's event batch — the host's credit, underrun, and ended events — then
refills the ring with at most one writePcm inside the credit the host
granted, which is what keeps a frame's hot path free of host queries. Nothing
plays without it: a track played before its first feed opens the tap inside
the first pump() that pours into it.
| Export | Signature | Description |
|---|---|---|
decodeWav |
(bytes: Uint8Array) => WavPcm |
Parse RIFF/WAVE into { sampleRate, channels, frames, data }. Throws on anything but 16-bit PCM, mono or stereo, at a rate in AUDIO_RATES. |
createWavPlayer |
() => WavPlayer |
A player holding one track at a time. |
WavPlayer is load(name) (a pak audio:wav.<name> entry) or
loadPcm(pcm), play(), pause(), toggle(), stop() (flush the ring and
rewind to frame 0), setVolume(0..1), pump(), playing(),
positionFrames(), durationFrames(), stats() ({ underruns }), and
dispose().
@pocketjs/framework/system-layers
What a system layer builds on. A system layer is guest code a product adds
to an application's bundle with tools/build.ts --layer=<module>. The
module is imported ahead of the application's entry and registers a mount
function; render() calls it after the application mounts. The application
imports nothing from this path.
| Export | Signature | Description |
|---|---|---|
registerSystemLayer |
(layer: (ops: HostOps) => (() => void) | null) => void |
Register a mount function. It returns its dispose function, or null when the host lacks what the layer needs. |
setFrameInputFilter |
(filter: ((input: FrameInput) => void) | null) => void |
Rewrite the frame's buttons, touches, hits and surfaces in place before the application reads them. One filter is active at a time. |
registerServicePump |
(pump: () => void) => () => void |
Run pump once per frame before the application's frame hooks; returns the function that removes it. |
suspendApp |
(suspended: boolean) => void |
Hold or release the application's frame callbacks, button handlers included. Native animations, timers and service deliveries continue. |
isAppSuspended |
() => boolean |
Whether the application is held. |
SystemFrameContext |
Solid context of boolean |
Handlers mounted under <SystemFrameContext.Provider value={true}> run while the application is held. |
packTouch |
(id: number, x: number, y: number) => number |
One contact as a frame's touch word, for a filter that plays input. |
openOsk |
() => OskController | null |
The on-screen keyboard that is open. |
ENUMS, SCREEN_W, SCREEN_H |
spec values | Property ordinals and the default screen size, for a layer that builds nodes through the operations. |
@pocketjs/framework/hot
function text(node: NodeMirror | undefined, value: string | number): void
function prop(node: NodeMirror | undefined, name: PropName, value: number): voidAn imperative, last-value-gated escape hatch for high-frequency HUD updates. Do not bind the same value reactively as well. Prefer paint-only transforms to layout properties and keep hot text inside a fixed-size cell.
@pocketjs/framework/host-config
function defineHostConfig<const C extends PocketHostConfig>(config: C): C
function isBuiltinHostId(host: string): boolean
function cargo(options?): CargoStep
function cmake(options?): CmakeStep
function make(options?): MakeStep
function compilerOnly(): CompilerOnlyStepdefineHostConfig({ host | hosts, app?, build? }) checks a host config and
returns it; pocket.host.config.ts exports the result as its default. Each
host/hosts entry is a pocket.host.json path relative to the config or a
built-in host id (isBuiltinHostId). An app section that breaks its schema
throws a TypeError listing each broken rule under /app. The step helpers
build a program's native recipe (CLI).
| Type | Meaning |
|---|---|
AppConfig |
The app section (Application config). |
AnimationTheme |
keyframes and animation, the content app.theme holds. |
AppViewport, SurfacesSpec |
app.viewport and app.surfaces. |
WorkerDeclarationSource |
app.worker, with channel sizes that may be "host". |
@pocketjs/framework/plan
This subpath resolves an application for a host, verifies build plans and holds the stable custom-host boundary:
| Export | Purpose |
|---|---|
resolveAppPlan(app, request, registry?) |
Check an app section and resolve it for request.target into a ResolvedBuildPlan, or return diagnostics with JSON Pointers under /app. request.configDirectory and request.projectRoot rebase entries from the config onto the project root. |
appIdentity(app, output), appOutput(app) |
The identity and artifact name a plan records, with their defaults. |
validatePlatformContractRegistry(registry) |
Check a capability and target registry before resolving against it. |
validateAppConfig(app) |
Schema diagnostics for an app section. |
canonicalJson, hashBuildPlanContent, finalizeBuildPlan |
The plan's canonical JSON and its planHash. |
verifyPlanHash(plan), verifyPlanProfile(plan) |
Check a plan's checksum, and that its recorded host contract validates and hashes to profileHash. |
planProfileDocument(profile) |
The host contract a plan records, without the application rate. |
extractHostBuildInputs(plan, options?) |
Verify a plan and project it onto stable native-host inputs. |
hostBuildEnvironment(inputs, options) |
Produce the target-neutral Cargo environment for a custom host. |
createHostExtension, isHostExtension |
A versioned, content-hashed adapter payload a plan may carry. |
vitaTitleId(applicationId) |
Derive the nine-character Vita Title ID from the application id. |
The plan is the compiler's input (tools/build.ts --plan); its field names
and hash rule are stable, and a plan may carry fields this repository does not
read. Custom hosts consume HostBuildInputs rather than retaining or
reinterpreting the whole plan. See Platform contracts.
Try any of these live in the playground, or start from Getting started.