@pushframe/sdk 0.1.4 → 0.1.8

package/lib/typescript/renderer/RecursiveRenderer.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { ReactElement } from 'react';
+import type { SchemaNode } from '../context/PushFrameContext';
+import type { ComponentRegistry } from '../registry/ComponentRegistry';
+export interface DispatchAction {
+    (actionName: string, payload?: Record<string, unknown>): void;
+}
+export interface RecursiveRendererProps {
+    node: SchemaNode;
+    /** Current merged data context for binding resolution. */
+    context: Record<string, unknown>;
+    registry: ComponentRegistry;
+    /** Handles all actions — built-ins and host-app bubbling. Provided by the slot component. */
+    dispatchAction: DispatchAction;
+    /** Shown when a component type is not found in the registry. */
+    fallbackComponent?: React.ReactNode;
+}
+/**
+ * Stateless recursive renderer. Evaluates schema nodes and produces React elements.
+ *
+ * - Evaluates `if` expression (string or non-string); returns null when falsy
+ * - Handles `visible` prop: returns null when visible resolves to false
+ * - Handles FlatList nodes with per-item context injection via `itemTemplate`
+ * - Supports `data` (transformer) and `items` (legacy) as FlatList data source
+ * - Resolves all prop bindings against current context
+ * - Merges `_propValues` into child context (custom component prop injection)
+ * - Wires actions to component event handler props
+ * - Looks up component in registry; renders fallback or null when not found
+ * - Recurses into children
+ */
+export declare function RecursiveRenderer({ node, context, registry, dispatchAction, fallbackComponent, }: RecursiveRendererProps): ReactElement | null;
+//# sourceMappingURL=RecursiveRenderer.d.ts.map

package/lib/typescript/renderer/RecursiveRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecursiveRenderer.d.ts","sourceRoot":"","sources":["../../../src/renderer/RecursiveRenderer.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAA8B,MAAM,6BAA6B,CAAC;AAC1F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAQvE,MAAM,WAAW,cAAc;IAC7B,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,CAAC;IACjB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,6FAA6F;IAC7F,cAAc,EAAE,cAAc,CAAC;IAC/B,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CACrC;AA4HD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,cAAc,EACd,iBAAiB,GAClB,EAAE,sBAAsB,GAAG,YAAY,GAAG,IAAI,CA0E9C"}

package/lib/typescript/renderer/bindingResolver.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Binding resolver for PushFrame {{expression}} syntax.
+ *
+ * Rules:
+ * - A value that is entirely "{{expr}}" resolves to the bound value (any type)
+ * - A value with inline bindings "Hello {{user.name}}" resolves to a string
+ * - Unresolved paths return undefined — never throws
+ * - Non-string values are returned as-is
+ */
+/**
+ * Resolve a single prop value against context.
+ *
+ * - String values: check for full binding "{{expr}}" or inline bindings "Hello {{name}}"
+ * - Non-string values: returned as-is
+ */
+export declare function resolveValue(value: unknown, context: Record<string, unknown>): unknown;
+/**
+ * Resolve all values in a props map against the context.
+ * Recursively resolves nested objects and arrays.
+ */
+export declare function resolveProps(props: Record<string, unknown> | undefined, context: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Recursively resolve binding expressions in a value (including nested objects/arrays).
+ */
+export declare function resolveDeep(value: unknown, context: Record<string, unknown>): unknown;
+//# sourceMappingURL=bindingResolver.d.ts.map

package/lib/typescript/renderer/bindingResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindingResolver.d.ts","sourceRoot":"","sources":["../../../src/renderer/bindingResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwBH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAsBtF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAYrF"}

package/lib/typescript/renderer/conditionalEvaluator.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Evaluate the `if` expression of a SchemaNode against the current context.
+ *
+ * Returns true  → node should render
+ * Returns false → node (and its entire subtree) should be skipped
+ *
+ * Falsy values: false, null, undefined, 0, "" all hide the node.
+ * When `ifExpr` is undefined/null the node always renders.
+ *
+ * Accepts `unknown` to match the transformer's `if?: unknown` output:
+ *   - String values are resolved as {{}} binding expressions
+ *   - Non-string values (boolean, number, null) are coerced directly
+ */
+export declare function evaluateIf(ifExpr: unknown, context: Record<string, unknown>): boolean;
+//# sourceMappingURL=conditionalEvaluator.d.ts.map

package/lib/typescript/renderer/conditionalEvaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditionalEvaluator.d.ts","sourceRoot":"","sources":["../../../src/renderer/conditionalEvaluator.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAUT"}

package/lib/typescript/renderer.d.ts

@@ -0,0 +1,29 @@
+import type { ReactElement } from 'react';
+import type { PushframeNode } from './schema';
+import type { ComponentRegistry } from './registry';
+import type { PushframeContext } from './bindings';
+import type { PushframeAction } from './schema';
+/**
+ * Called by the host app whenever an action is triggered.
+ * `eventName` is the prop key (e.g. "onPress").
+ * `action` is the resolved action descriptor from the schema.
+ */
+export type ActionHandler = (eventName: string, action: PushframeAction) => void;
+interface RenderNodeOptions {
+    node: PushframeNode;
+    context: PushframeContext;
+    registry: ComponentRegistry;
+    onAction?: ActionHandler;
+    /** Key to help React reconcile siblings. */
+    key?: string;
+}
+/**
+ * Recursively render a single PushframeNode.
+ *
+ * Returns null when:
+ *  - The node's condition evaluates to false
+ *  - The node's type is not found in the registry
+ */
+export declare function renderNode({ node, context, registry, onAction, key, }: RenderNodeOptions): ReactElement | null;
+export {};
+//# sourceMappingURL=renderer.d.ts.map

package/lib/typescript/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/renderer.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;AAEjF,UAAU,iBAAiB;IACzB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,GAAG,GACJ,EAAE,iBAAiB,GAAG,YAAY,GAAG,IAAI,CA+DzC"}

package/lib/typescript/schema.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Pushframe Schema — typed definitions for screen definitions.
+ *
+ * A screen is described as a tree of PushframeNode objects.
+ * Props can be static values OR data-bindings via { "$bind": "path.to.value" }.
+ * Conditions gate whether a node renders at all.
+ * Actions declare event handlers; the host app is responsible for handling them.
+ */
+export declare const SCHEMA_VERSION: "1.0";
+export type SchemaVersion = typeof SCHEMA_VERSION;
+/**
+ * A binding reference to a value in the runtime context.
+ * e.g. { "$bind": "user.firstName" }
+ */
+export interface Binding {
+    readonly $bind: string;
+}
+export declare function isBinding(value: unknown): value is Binding;
+/**
+ * A prop value is either a static primitive / object, or a binding.
+ */
+export type PropValue = string | number | boolean | null | Binding | PropValue[] | {
+    [key: string]: PropValue;
+};
+export type PropsMap = Record<string, PropValue>;
+/**
+ * A condition gates whether a node should render.
+ *
+ * Supported operators:
+ *   equals     — strict equality (===)
+ *   notEquals  — strict inequality (!==)
+ *   truthy     — if the resolved value is truthy (no `value` needed)
+ *   falsy      — if the resolved value is falsy  (no `value` needed)
+ */
+export type ConditionOperator = 'equals' | 'notEquals' | 'truthy' | 'falsy';
+export interface Condition {
+    /** The binding (or static value) to test. */
+    readonly if: Binding | PropValue;
+    /** Comparison operator. Defaults to "truthy" when omitted. */
+    readonly operator?: ConditionOperator;
+    /**
+     * The right-hand side value to compare against.
+     * Required for `equals` / `notEquals`; ignored for `truthy` / `falsy`.
+     */
+    readonly equals?: PropValue;
+}
+/** Navigate to another screen by ID. */
+export interface NavigateAction {
+    readonly type: 'navigate';
+    readonly screen: string;
+    readonly params?: Record<string, PropValue>;
+}
+/** Emit a named custom event. The host app decides what to do with it. */
+export interface CustomAction {
+    readonly type: 'custom';
+    readonly event: string;
+    readonly payload?: Record<string, PropValue>;
+}
+export type PushframeAction = NavigateAction | CustomAction;
+export type ActionsMap = Record<string, PushframeAction>;
+/**
+ * A single node in the UI tree.
+ *
+ * `type` maps to a registered component (e.g. "stack", "text", "button", "image").
+ * `props` are passed (after binding resolution) directly to the component.
+ * `children` are rendered recursively.
+ * `conditions` — when present, node is skipped if the condition evaluates to false.
+ * `actions` — event handler definitions; passed to the component as resolved callbacks.
+ */
+export interface PushframeNode {
+    readonly type: string;
+    readonly props?: PropsMap;
+    readonly children?: readonly PushframeNode[];
+    readonly conditions?: Condition;
+    readonly actions?: ActionsMap;
+}
+export interface ScreenDefinition {
+    readonly schemaVersion: SchemaVersion;
+    readonly id: string;
+    readonly root: PushframeNode;
+    /** Optional display name — used for debugging / logging. */
+    readonly name?: string;
+}
+//# sourceMappingURL=schema.d.ts.map

package/lib/typescript/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,eAAO,MAAM,cAAc,EAAG,KAAc,CAAC;AAC7C,MAAM,MAAM,aAAa,GAAG,OAAO,cAAc,CAAC;AAMlD;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAO1D;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,OAAO,GACP,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAMjD;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5E,MAAM,WAAW,SAAS;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAMD,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAC7C;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAC9C;AAED,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,YAAY,CAAC;AAE5D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAMzD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;CAC/B;AAMD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/lib/typescript/transformer/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Craft.js → PushFrame SDUI transformer
+ *
+ * Converts a Craft.js editor schema (produced by the dashboard) into the
+ * SDUINode tree consumed by the SDK's RecursiveRenderer at runtime.
+ *
+ * This module is intended for use by the backend/service layer or the
+ * dashboard — it is NOT executed inside the React Native app at runtime.
+ */
+import type { Action, SchemaNode } from '../context/PushFrameContext';
+export type CraftNode = {
+    type: {
+        resolvedName: string;
+    };
+    props?: Record<string, unknown>;
+    nodes?: string[];
+    parent?: string;
+};
+export type CraftSchema = Record<string, CraftNode>;
+/**
+ * The SDUI node shape produced by this transformer and consumed by the SDK's
+ * RecursiveRenderer. Aligned with `SchemaNode` from the SDK context.
+ */
+export interface SDUINode extends SchemaNode {
+    id: string;
+    type: string;
+    props: Record<string, unknown>;
+    children?: SDUINode[];
+    /** FlatList per-item render template. */
+    itemTemplate?: SDUINode;
+    /** Conditional render expression. Falsy → node is hidden. */
+    if?: unknown;
+    actions?: Action[];
+}
+export interface CustomComponentDef {
+    rootNodeId: string;
+    nodes: CraftSchema;
+}
+export type CustomComponentsMap = Record<string, CustomComponentDef>;
+/**
+ * Convert a Craft.js editor schema into an SDUINode tree ready for the SDK's
+ * RecursiveRenderer.
+ *
+ * @param craftJson   - The full Craft.js node map (keyed by node ID, must include "ROOT").
+ * @param customComponents - Optional map of reusable component definitions.
+ * @returns The root SDUINode.
+ */
+export declare function transformCraftToSDUI(craftJson: CraftSchema, customComponents?: CustomComponentsMap): SDUINode;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/transformer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transformer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAItE,MAAM,MAAM,SAAS,GAAG;IACpB,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AA+BpD;;;GAGG;AACH,MAAM,WAAW,QAAS,SAAQ,UAAU;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;IACtB,yCAAyC;IACzC,YAAY,CAAC,EAAE,QAAQ,CAAC;IACxB,6DAA6D;IAC7D,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AA0SD,MAAM,WAAW,kBAAkB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAonBrE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAChC,SAAS,EAAE,WAAW,EACtB,gBAAgB,GAAE,mBAAwB,GAC3C,QAAQ,CAOV"}

package/lib/typescript/transport.d.ts

@@ -0,0 +1,19 @@
+import type { ScreenDefinition } from './schema';
+/**
+ * Fetch a screen definition from the Pushframe server.
+ *
+ * URL: GET {serverUrl}/screens/{screenId}?projectKey={projectKey}
+ *
+ * Handles both the native SDK format ({ schemaVersion, id, root })
+ * and the server envelope format ({ key, version, schema, publishedAt }).
+ *
+ * Results are cached in memory for the lifetime of the JS bundle.
+ * Call `clearScreenCache()` to force a refetch (e.g. on logout or hard reload).
+ */
+export declare function fetchScreenDefinition(serverUrl: string, projectKey: string, screenId: string): Promise<ScreenDefinition>;
+/**
+ * Invalidate the entire in-memory screen cache.
+ * Useful after a forced refresh or when the project key changes.
+ */
+export declare function clearScreenCache(): void;
+//# sourceMappingURL=transport.d.ts.map

package/lib/typescript/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAiB,MAAM,UAAU,CAAC;AAwDhE;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC,CAwB3B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/package.json

@@ -1,27 +1,20 @@
 {
   "name": "@pushframe/sdk",
-  "version": "0.1.4",
+  "version": "0.1.8",
   "description": "Pushframe React Native SDK — Server-Driven UI rendering engine",
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
-  "react-native": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "react-native": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "default": "./dist/index.mjs"
-    }
-  },
+  "main": "lib/commonjs/index.js",
+  "module": "lib/module/index.js",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "types": "lib/typescript/index.d.ts",
   "files": [
-    "dist",
+    "src",
+    "lib",
     "README.md"
   ],
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "bob build",
+    "prepare": "bob build",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src --ext .ts,.tsx"
   },
@@ -33,9 +26,18 @@
   "devDependencies": {
     "@types/react": "^18.2.0",
     "@types/react-native": "^0.73.0",
-    "tsup": "^8.0.0",
+    "react-native-builder-bob": "latest",
     "typescript": "^5.4.0"
   },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      "typescript"
+    ]
+  },
   "keywords": [
     "react-native",
     "server-driven-ui",

package/src/PushframeProvider.tsx

@@ -0,0 +1,119 @@
+import React, { createContext, useContext, useMemo } from 'react';
+import type { ReactNode } from 'react';
+import { ComponentRegistry, createDefaultRegistry } from './registry';
+import type { PushframeComponent } from './registry';
+import type { PushframeContext } from './bindings';
+import type { ActionHandler } from './renderer';
+
+export const DEFAULT_SERVER_URL = 'http://localhost:3001';
+
+// ---------------------------------------------------------------------------
+// Context shape
+// ---------------------------------------------------------------------------
+
+interface PushframeContextValue {
+  /** Runtime data that screen definitions bind to via { "$bind": "..." }. */
+  context: PushframeContext;
+
+  /** Component registry used by all screens under this provider. */
+  registry: ComponentRegistry;
+
+  /** Identifies which Pushframe project's screens to fetch. */
+  projectKey: string;
+
+  /** Base URL of the Pushframe server. Defaults to http://localhost:3001. */
+  serverUrl: string;
+
+  /** Optional global action handler. */
+  onAction?: ActionHandler;
+}
+
+const PushframeCtx = createContext<PushframeContextValue | null>(null);
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+export function usePushframe(): PushframeContextValue {
+  const value = useContext(PushframeCtx);
+  if (!value) {
+    throw new Error('[Pushframe] usePushframe() must be called inside a <PushframeProvider>.');
+  }
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export interface PushframeProviderProps {
+  /**
+   * The Pushframe project key. All screens fetched under this provider will
+   * be scoped to this project.
+   */
+  projectKey: string;
+
+  /**
+   * Base URL of the Pushframe server.
+   * @default "http://localhost:3001"
+   */
+  serverUrl?: string;
+
+  /**
+   * Runtime data (user info, feature flags, etc.) that screen definitions
+   * can bind to via { "$bind": "path.to.value" }.
+   */
+  context: PushframeContext;
+
+  /**
+   * Optional pre-configured registry. When omitted, the default registry
+   * (stack, scrollview, flatlist, text, button, image) is used.
+   * Takes precedence over `customComponents` when both are provided.
+   */
+  registry?: ComponentRegistry;
+
+  /**
+   * Custom components to add on top of the default registry.
+   * Map of type string → component, e.g. `{ 'my-card': MyCardComponent }`.
+   * These override any built-in component with the same type string.
+   * Ignored when `registry` is also provided.
+   */
+  customComponents?: Record<string, PushframeComponent>;
+
+  /**
+   * Called whenever an action is triggered from a rendered screen.
+   * The host app is responsible for handling navigate / custom actions.
+   */
+  onAction?: ActionHandler;
+
+  children: ReactNode;
+}
+
+export function PushframeProvider({
+  projectKey,
+  serverUrl = DEFAULT_SERVER_URL,
+  context,
+  registry,
+  customComponents,
+  onAction,
+  children,
+}: PushframeProviderProps) {
+  const resolvedRegistry = useMemo(() => {
+    if (registry) return registry;
+    const defaultReg = createDefaultRegistry();
+    if (customComponents) {
+      for (const [type, component] of Object.entries(customComponents)) {
+        defaultReg.register(type, component);
+      }
+    }
+    return defaultReg;
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [registry, customComponents]);
+
+  const value = useMemo<PushframeContextValue>(
+    () => ({ projectKey, serverUrl, context, registry: resolvedRegistry, onAction }),
+    [projectKey, serverUrl, context, resolvedRegistry, onAction],
+  );
+
+  return <PushframeCtx.Provider value={value}>{children}</PushframeCtx.Provider>;
+}

package/src/PushframeScreen.tsx

@@ -0,0 +1,107 @@
+import React, { useEffect, useState } from 'react';
+import type { ReactElement } from 'react';
+import { usePushframe } from './PushframeProvider';
+import { renderNode } from './renderer';
+import { fetchScreenDefinition } from './transport';
+import type { ScreenDefinition } from './schema';
+import type { ActionHandler } from './renderer';
+import { SCHEMA_VERSION } from './schema';
+
+export interface PushframeScreenProps {
+  /**
+   * Fetch the screen definition from the server by ID.
+   * Requires `projectKey` and `serverUrl` to be set on the parent
+   * <PushframeProvider>.
+   *
+   * Mutually exclusive with `definition`.
+   */
+  screenId?: string;
+
+  /**
+   * Use a locally-provided screen definition (static / offline mode).
+   * Mutually exclusive with `screenId`.
+   */
+  definition?: ScreenDefinition;
+
+  /**
+   * Optional per-screen action handler. Takes precedence over the global
+   * handler set on <PushframeProvider>.
+   */
+  onAction?: ActionHandler;
+
+  /**
+   * Rendered while the screen definition is being fetched from the server.
+   * Defaults to null (renders nothing).
+   */
+  fallback?: ReactElement | null;
+
+  /**
+   * Rendered when the fetch fails.
+   * Defaults to null (renders nothing, error is logged to console).
+   */
+  errorFallback?: ReactElement | null;
+}
+
+export function PushframeScreen({
+  screenId,
+  definition: staticDefinition,
+  onAction,
+  fallback = null,
+  errorFallback = null,
+}: PushframeScreenProps) {
+  if (!screenId && !staticDefinition) {
+    throw new Error('[Pushframe] <PushframeScreen> requires either screenId or definition.');
+  }
+
+  const { context, registry, projectKey, serverUrl, onAction: globalOnAction } = usePushframe();
+  const effectiveOnAction = onAction ?? globalOnAction;
+
+  // When a static definition is passed we skip the fetch entirely.
+  const [fetchedDefinition, setFetchedDefinition] = useState<ScreenDefinition | null>(null);
+  const [fetchError, setFetchError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!screenId) return;
+
+    let cancelled = false;
+    setFetchedDefinition(null);
+    setFetchError(null);
+
+    fetchScreenDefinition(serverUrl, projectKey, screenId)
+      .then((def) => {
+        if (!cancelled) setFetchedDefinition(def);
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          console.error(`[Pushframe] Error fetching screen "${screenId}":`, error.message);
+          setFetchError(error);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [screenId, projectKey, serverUrl]);
+
+  const definition = staticDefinition ?? fetchedDefinition;
+
+  if (!definition) {
+    return fetchError ? errorFallback : fallback;
+  }
+
+  if (definition.schemaVersion !== SCHEMA_VERSION) {
+    console.warn(
+      `[Pushframe] Schema version mismatch: expected "${SCHEMA_VERSION}", ` +
+        `got "${definition.schemaVersion}" for screen "${definition.id}".`,
+    );
+  }
+
+  return renderNode({
+    node: definition.root,
+    context,
+    registry,
+    ...(effectiveOnAction !== undefined && { onAction: effectiveOnAction }),
+    key: definition.id,
+  });
+}

package/src/bindings.ts

@@ -0,0 +1,72 @@
+import { isBinding } from './schema';
+import type { PropValue, PropsMap } from './schema';
+
+/**
+ * Runtime context passed into the renderer.
+ * Any JSON-serialisable data structure is valid.
+ */
+export type PushframeContext = Record<string, unknown>;
+
+/**
+ * Resolve a dot-separated path against an object.
+ *
+ * e.g. resolvePath({ user: { firstName: "Alex" } }, "user.firstName") → "Alex"
+ *
+ * Returns undefined when any segment along the path is absent.
+ */
+export function resolvePath(context: PushframeContext, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = context;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+/**
+ * Recursively resolve all $bind references in a PropValue against the context.
+ *
+ * - Binding objects  → resolved to the context value (or undefined if missing)
+ * - Arrays           → each element resolved
+ * - Plain objects    → each value resolved
+ * - Primitives       → returned as-is
+ */
+export function resolveValue(value: PropValue, context: PushframeContext): unknown {
+  if (isBinding(value)) {
+    return resolvePath(context, value.$bind);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveValue(item, context));
+  }
+
+  if (typeof value === 'object' && value !== null) {
+    const resolved: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, PropValue>)) {
+      resolved[k] = resolveValue(v, context);
+    }
+    return resolved;
+  }
+
+  // string | number | boolean | null
+  return value;
+}
+
+/**
+ * Resolve all entries in a props map against the context.
+ * Returns a plain Record<string, unknown> ready to spread onto a component.
+ */
+export function resolveProps(
+  props: PropsMap | undefined,
+  context: PushframeContext,
+): Record<string, unknown> {
+  if (!props) return {};
+  const resolved: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(props)) {
+    resolved[key] = resolveValue(value, context);
+  }
+  return resolved;
+}