react-native-revnix 1.7.0 → 1.8.0

package/dist/blocks/locale.js

@@ -191,6 +191,11 @@ function localizeBlockDoc(doc, locale) {
         ...doc,
         defaultLocale: chain[0],
         blocks: doc.blocks.map((b) => localizeBlock(b, lookup)),
+        ...(doc.screens
+            ? {
+                screens: doc.screens.map((screen) => screen.map((b) => localizeBlock(b, lookup))),
+            }
+            : {}),
     };
 }
 const LINK_LABEL_ALIASES = {

package/dist/blocks/types.d.ts

@@ -112,12 +112,14 @@ export interface BlockStyle {
 /** REV-262: draw a block only while its plan card is (or is not) the selected
  *  one. Ignored outside a package card — a root block is always drawn. */
 export type BlockVisibility = "selected" | "unselected";
-export type BlockAction = "close";
+/** `close` dismisses the paywall; `next`/`back` move between onboarding
+ *  screens and only appear inside `screens`. */
+export type BlockAction = "close" | "next" | "back";
 export interface TextBlock {
     id: string;
     type: "text";
     text: string;
-    /** Tapping this block dismisses the paywall. See BlockAction. */
+    /** What tapping this block does. See BlockAction. */
     action?: BlockAction;
     style?: BlockStyle;
     /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -134,7 +136,7 @@ export interface ImageBlock {
     shape?: "rect" | "circle";
     fit?: "cover" | "contain";
     placeholder?: string;
-    /** Tapping this block dismisses the paywall. See BlockAction. */
+    /** What tapping this block does. See BlockAction. */
     action?: BlockAction;
     style?: BlockStyle;
     /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -182,8 +184,9 @@ export interface ButtonBlock {
     id: string;
     type: "button";
     label: string;
-    /** `close` turns this button into a dismiss ("Not now") instead of the
-     *  purchase CTA, which is what a button means by default. */
+    /** `close` turns this button into a dismiss ("Not now"), and `next`/`back`
+     *  into onboarding navigation, instead of the purchase CTA, which is what a
+     *  button means by default. */
     action?: BlockAction;
     style?: BlockStyle;
     /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -311,6 +314,10 @@ export interface PaywallBlockDoc {
     accentInk: string;
     fontFamily?: string;
     blocks: PaywallBlock[];
+    /** Onboarding: intro screens shown in order before `blocks`, which stays
+     *  the last (purchase) screen. They share the doc's palette, layout and
+     *  locale table. Absent or empty = `blocks` alone. */
+    screens?: PaywallBlock[][];
     /** REV-271: the language the blocks' own copy is written in. Absent = "en".
      *  Never a key in a stored doc's `locales` — the tree IS that language's
      *  version. A localized copy names the language it was localized to. */
@@ -341,3 +348,11 @@ export declare const DESIGN_CANVAS: {
  *  bug this feature exists to fix. Two close buttons is merely ugly, so the
  *  tie breaks toward always having one. */
 export declare function hasCloseAction(blocks: PaywallBlock[]): boolean;
+export declare function onboardingScreen(doc: PaywallBlockDoc, index: number): {
+    blocks: PaywallBlock[];
+    dots?: {
+        count: number;
+        active: number;
+    };
+};
+export declare function stepScreen(doc: PaywallBlockDoc, index: number, action: BlockAction | undefined): number | undefined;

package/dist/blocks/types.js

@@ -13,6 +13,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DESIGN_CANVAS = void 0;
 exports.hasCloseAction = hasCloseAction;
+exports.onboardingScreen = onboardingScreen;
+exports.stepScreen = stepScreen;
 /** The device screen `canvas` designs are authored against. */
 exports.DESIGN_CANVAS = { width: 393, height: 852 };
 /** Does this tree author a dismiss affordance that is CERTAIN to render?
@@ -43,3 +45,21 @@ function hasCloseAction(blocks) {
             : (b.type === "text" || b.type === "image" || b.type === "button") &&
                 b.action === "close");
 }
+function onboardingScreen(doc, index) {
+    const intro = doc.screens?.[index];
+    if (intro === undefined)
+        return { blocks: doc.blocks };
+    return {
+        blocks: intro,
+        dots: { count: doc.screens.length + 1, active: index },
+    };
+}
+function stepScreen(doc, index, action) {
+    if (index >= (doc.screens?.length ?? 0))
+        return undefined;
+    if (action === "next")
+        return index + 1;
+    if (action === "back" && index > 0)
+        return index - 1;
+    return undefined;
+}

package/dist/esm/blocks/locale.js

@@ -183,6 +183,11 @@ export function localizeBlockDoc(doc, locale) {
         ...doc,
         defaultLocale: chain[0],
         blocks: doc.blocks.map((b) => localizeBlock(b, lookup)),
+        ...(doc.screens
+            ? {
+                screens: doc.screens.map((screen) => screen.map((b) => localizeBlock(b, lookup))),
+            }
+            : {}),
     };
 }
 const LINK_LABEL_ALIASES = {

package/dist/esm/blocks/types.js

@@ -39,3 +39,21 @@ export function hasCloseAction(blocks) {
             : (b.type === "text" || b.type === "image" || b.type === "button") &&
                 b.action === "close");
 }
+export function onboardingScreen(doc, index) {
+    const intro = doc.screens?.[index];
+    if (intro === undefined)
+        return { blocks: doc.blocks };
+    return {
+        blocks: intro,
+        dots: { count: doc.screens.length + 1, active: index },
+    };
+}
+export function stepScreen(doc, index, action) {
+    if (index >= (doc.screens?.length ?? 0))
+        return undefined;
+    if (action === "next")
+        return index + 1;
+    if (action === "back" && index > 0)
+        return index - 1;
+    return undefined;
+}

package/dist/esm/ui/RevnixBlockPaywall.js

@@ -24,7 +24,7 @@ import { backgroundLayers, coverPlacement, } from "../blocks/background.js";
 import { detectLocale, linkLabels, localizeBlockDoc } from "../blocks/locale.js";
 import { resolveTags, timerText } from "../blocks/tags.js";
 import { canvasMetrics, effectiveStyle, isVisible, packageContext, selectedPackageId, toggleSelection, } from "../blocks/selection.js";
-import { DESIGN_CANVAS, hasCloseAction, } from "../blocks/types.js";
+import { DESIGN_CANVAS, hasCloseAction, onboardingScreen, stepScreen, } from "../blocks/types.js";
 /** CSS angle (0 = up, 90 = right) → RN gradient start/end points. */
 function angleToPoints(angle) {
     const rad = (angle * Math.PI) / 180;
@@ -240,7 +240,7 @@ function FallbackClose({ doc, onPress, safeAreaTop, }) {
 /** Text blocks always render inside a View: a style may carry both typography
  *  and box properties (a round chip is a 34pt circle with a centered glyph),
  *  and RN cannot centre a glyph inside <Text> the way flexbox does. */
-function BlockText({ text, style, ctx, inherited, onPress, }) {
+function BlockText({ text, style, ctx, inherited, onPress, pressLabel, }) {
     const styleCtx = { ...ctx.style, fontSize: inherited.fontSize };
     // The block's own typography is folded into the inherited set first, so
     // em letter-spacing and unitless line-height resolve against whichever font
@@ -255,7 +255,7 @@ function BlockText({ text, style, ctx, inherited, onPress, }) {
     // wrapping a styled View would leave a pinned chip resolving its offsets
     // against a zero-sized parent.
     if (onPress) {
-        return (React.createElement(Pressable, { accessibilityRole: "button", accessibilityLabel: "Close", hitSlop: 8, onPress: onPress, style: toViewStyle(style, styleCtx) }, body));
+        return (React.createElement(Pressable, { accessibilityRole: "button", accessibilityLabel: pressLabel, hitSlop: 8, onPress: onPress, style: toViewStyle(style, styleCtx) }, body));
     }
     return React.createElement(View, { style: toViewStyle(style, styleCtx) }, body);
 }
@@ -294,27 +294,34 @@ function Carousel({ pages, autoAdvance, doc, }) {
                     setPage(Math.round(e.nativeEvent.contentOffset.x / size.width));
                 }
             } }, pages.map((node, i) => (React.createElement(View, { key: i, style: size }, node)))),
-        pages.length > 1 ? (React.createElement(View, { pointerEvents: "none", style: {
+        pages.length > 1 ? (React.createElement(Dots, { count: pages.length, active: page, doc: doc, style: { bottom: 8 } })) : null));
+}
+function Dots({ count, active, doc, style, }) {
+    return (React.createElement(View, { pointerEvents: "none", style: [
+            {
                 position: "absolute",
-                bottom: 8,
                 left: 0,
                 right: 0,
                 flexDirection: "row",
                 justifyContent: "center",
                 gap: 6,
-            } }, pages.map((_, i) => (React.createElement(View, { key: i, style: {
-                width: 6,
-                height: 6,
-                borderRadius: 3,
-                backgroundColor: i === page ? doc.accent : withAlpha(doc.textColor, 0.3),
-            } }))))) : null));
+            },
+            style,
+        ] }, Array.from({ length: count }, (_, i) => (React.createElement(View, { key: i, style: {
+            width: 6,
+            height: 6,
+            borderRadius: 3,
+            backgroundColor: i === active ? doc.accent : withAlpha(doc.textColor, 0.3),
+        } })))));
 }
-/** The press handler for a block the design marks as the close, or undefined
- *  when it is not one (or the host wired no dismissal). One helper so text,
- *  image and button blocks cannot drift on what "action: close" means. */
-function closePress(block, ctx) {
-    return block.action === "close" && ctx.onClose ? ctx.onClose : undefined;
+function actionPress(block, ctx) {
+    return block.action === "close" ? ctx.onClose : ctx.navigate(block.action);
 }
+const ACTION_LABEL = {
+    close: "Close",
+    next: "Next",
+    back: "Back",
+};
 /** Typography that is NOT inherited (decoration) — everything else already
  *  arrives through the inherited set. */
 function textOnly(s, ctx) {
@@ -439,7 +446,7 @@ function Block({ block, ctx, pkg, inherited, selection, }) {
     const size = text.fontSize;
     switch (block.type) {
         case "text":
-            return (React.createElement(BlockText, { text: resolveTags(block.text, pkg, ctx.packages), style: style, ctx: ctx, inherited: inherited, onPress: closePress(block, ctx) }));
+            return (React.createElement(BlockText, { text: resolveTags(block.text, pkg, ctx.packages), style: style, ctx: ctx, inherited: inherited, onPress: actionPress(block, ctx), pressLabel: block.action === "close" ? "Close" : undefined }));
         case "timer":
             return React.createElement(Timer, { block: block, style: style, ctx: ctx, inherited: inherited });
         case "toggle": {
@@ -470,12 +477,10 @@ function Block({ block, ctx, pkg, inherited, selection, }) {
                     s.aspectRatio !== undefined ||
                     (s.top !== undefined && s.bottom !== undefined) ||
                     s.flex !== undefined);
-            // An icon the design marks as the close (REV-252). Same rule as text:
-            // the whole box is the target, and the style lands on the Pressable so
-            // a pinned icon keeps its offsets.
-            const closeImage = image ? closePress(block, ctx) : undefined;
-            const ImageBox = closeImage ? Pressable : View;
-            return (React.createElement(ImageBox, { accessibilityRole: closeImage ? "button" : undefined, accessibilityLabel: closeImage ? "Close" : undefined, hitSlop: closeImage ? 8 : undefined, onPress: closeImage, style: [
+            const action = block.type === "image" ? block.action : undefined;
+            const imagePress = actionPress({ action }, ctx);
+            const ImageBox = imagePress ? Pressable : View;
+            return (React.createElement(ImageBox, { accessibilityRole: imagePress ? "button" : undefined, accessibilityLabel: imagePress && action ? ACTION_LABEL[action] : undefined, hitSlop: imagePress ? 8 : undefined, onPress: imagePress, style: [
                     sized ? null : { height: 160 },
                     { borderRadius: round ? 9999 : sized ? 0 : 16, overflow: "hidden", flexShrink: 0 },
                     view,
@@ -516,12 +521,13 @@ function Block({ block, ctx, pkg, inherited, selection, }) {
             // A button the design marks as the close dismisses instead of buying,
             // and takes no accent fill: the CTA must stay the one accented thing on
             // the screen, or a "Not now" competes with "Subscribe" for the eye.
-            const close = closePress(block, ctx);
+            const close = block.action === "close" ? ctx.onClose : undefined;
+            const navigates = block.action === "next" || block.action === "back";
             // A purchase in flight: the button keeps its box and fill, loses its
             // label to a spinner in the ink colour, and ignores taps. A close
             // button is never blocked — the user can always leave.
-            const busy = !close && ctx.loading;
-            return (React.createElement(Pressable, { accessibilityRole: "button", accessibilityState: { disabled: busy, busy }, disabled: busy, onPress: close ?? ctx.onPurchase, style: ({ pressed }) => [
+            const busy = !close && !navigates && ctx.loading;
+            return (React.createElement(Pressable, { accessibilityRole: "button", accessibilityState: { disabled: busy, busy }, disabled: busy, onPress: navigates ? actionPress(block, ctx) : (close ?? ctx.onPurchase), style: ({ pressed }) => [
                     {
                         backgroundColor: close ? "transparent" : doc.accent,
                         borderRadius: 12,
@@ -678,6 +684,13 @@ export function RevnixBlockPaywall(props) {
     const doc = React.useMemo(() => localizeBlockDoc(props.doc, props.locale ?? detectLocale()), [props.doc, props.locale]);
     const [internalSelected, setInternalSelected] = React.useState(undefined);
     const [shownAt] = React.useState(Date.now);
+    const [screenIndex, setScreenIndex] = React.useState(0);
+    const [screenDoc, setScreenDoc] = React.useState(props.doc);
+    if (screenDoc !== props.doc) {
+        setScreenDoc(props.doc);
+        setScreenIndex(0);
+    }
+    const screen = onboardingScreen(doc, screenIndex);
     // Contract §1: host → own tap → design highlight → first package, each
     // only when the offering carries it.
     const selectedId = selectedPackageId(packages, props.selectedPackageId, internalSelected, props.highlightPackageId);
@@ -713,6 +726,10 @@ export function RevnixBlockPaywall(props) {
         onTerms: props.onTerms,
         onPrivacy: props.onPrivacy,
         onClose: props.onClose,
+        navigate: (action) => {
+            const to = stepScreen(doc, screenIndex, action);
+            return to === undefined ? undefined : () => setScreenIndex(to);
+        },
         footer: props.footer,
         heroImageUrl: props.heroImageUrl,
         gradient: props.gradient,
@@ -721,14 +738,14 @@ export function RevnixBlockPaywall(props) {
         loading: props.loading === true,
         shownAt,
     };
-    const children = doc.blocks.map((block) => (React.createElement(Block, { key: block.id, block: block, ctx: ctx, pkg: packages.find((p) => p.packageId === selectedId) ?? packages[0], inherited: rootText })));
+    const children = screen.blocks.map((block) => (React.createElement(Block, { key: block.id, block: block, ctx: ctx, pkg: packages.find((p) => p.packageId === selectedId) ?? packages[0], inherited: rootText })));
     // REV-252: the renderer's own close, drawn only for a design that authors
     // none. Rendered as a sibling of the tree — outside the canvas scale — so
     // it keeps its tap size and its distance from the screen edge whatever the
     // device width does to the design.
     const safeAreaTop = props.safeAreaTop ??
         (Platform.OS === "android" ? (StatusBar.currentHeight ?? 0) : 0);
-    const fallbackClose = props.onClose && !hasCloseAction(doc.blocks) ? (React.createElement(FallbackClose, { doc: doc, onPress: props.onClose, safeAreaTop: safeAreaTop })) : null;
+    const fallbackClose = props.onClose && !hasCloseAction(screen.blocks) ? (React.createElement(FallbackClose, { doc: doc, onPress: props.onClose, safeAreaTop: safeAreaTop })) : null;
     const [width, setWidth] = React.useState(null);
     const [viewportHeight, setViewportHeight] = React.useState(null);
     if (doc.layout === "canvas") {
@@ -749,7 +766,7 @@ export function RevnixBlockPaywall(props) {
         const canvasHeight = metrics?.scaledHeight ?? DESIGN_CANVAS.height;
         const left = metrics?.left ?? 0;
         return (React.createElement(ScreenBackground, { doc: doc, gradient: props.gradient, blur: props.blur, onDiagnostic: props.onDiagnostic, style: [{ flex: 1 }, props.style] },
-            React.createElement(ScrollView, { contentContainerStyle: { height: canvasHeight }, 
+            React.createElement(ScrollView, { key: screenIndex, contentContainerStyle: { height: canvasHeight }, 
                 // A designed screen never shows a scrollbar — the web preview has
                 // none, and in an RTL app the indicator lands on the left edge of
                 // the artwork. When nothing overflows, scrolling is off entirely so
@@ -773,15 +790,18 @@ export function RevnixBlockPaywall(props) {
                                 { translateY: -((canvasHeight / scale) * (1 - scale)) / 2 },
                                 { scale },
                             ],
-                        } }, children))),
+                        } },
+                        children,
+                        screen.dots ? (React.createElement(Dots, { count: screen.dots.count, active: screen.dots.active, doc: doc, style: { top: 20, zIndex: 50 } })) : null))),
             fallbackClose));
     }
     return (React.createElement(ScreenBackground, { doc: doc, gradient: props.gradient, blur: props.blur, onDiagnostic: props.onDiagnostic, style: [{ flex: 1 }, props.style] },
-        React.createElement(ScrollView, { contentContainerStyle: {
+        React.createElement(ScrollView, { key: screenIndex, contentContainerStyle: {
                 gap: 12,
                 paddingHorizontal: 20,
                 paddingTop: 18,
                 paddingBottom: 30,
             }, showsVerticalScrollIndicator: false, alwaysBounceVertical: false, overScrollMode: "never" }, children),
+        screen.dots ? (React.createElement(Dots, { count: screen.dots.count, active: screen.dots.active, doc: doc, style: { top: 20 + safeAreaTop, zIndex: 50 } })) : null,
         fallbackClose));
 }

package/dist/esm/ui/RevnixPaywall.js

@@ -38,7 +38,16 @@ function asBlockDoc(value) {
         typeof doc.textColor === "string" &&
         typeof doc.accent === "string" &&
         typeof doc.accentInk === "string"
-        ? doc
+        ? {
+            ...doc,
+            ...(doc.screens !== undefined
+                ? {
+                    screens: Array.isArray(doc.screens)
+                        ? doc.screens.filter((s) => Array.isArray(s) && s.length > 0)
+                        : [],
+                }
+                : {}),
+        }
         : null;
 }
 export const DEFAULT_PAYWALL_THEME = {
@@ -251,7 +260,7 @@ export function RevnixPaywall(props) {
     // arrives after a placeholder (or is swapped by an A/B assignment) would
     // otherwise crash on "rendered more hooks than during the previous render".
     const { config } = props;
-    const blocks = asBlockDoc(config.blocks);
+    const blocks = React.useMemo(() => asBlockDoc(config.blocks), [config.blocks]);
     // Both sinks fire when both are wired; nil when neither is, which is what
     // stops the renderer building a message nobody will read.
     const renderDiagnostic = client?.reportRenderDiagnostic || props.onDiagnostic

package/dist/esm/version.js

@@ -1,4 +1,4 @@
 // L3: the single source of the SDK version inside src/. Must match
 // package.json "version" — version.test.ts fails the build when they drift
 // (they had: client.ts said 0.7.0 while the package shipped 0.9.0).
-export const SDK_VERSION = "1.7.0";
+export const SDK_VERSION = "1.8.0";

package/dist/ui/RevnixBlockPaywall.js

@@ -276,7 +276,7 @@ function FallbackClose({ doc, onPress, safeAreaTop, }) {
 /** Text blocks always render inside a View: a style may carry both typography
  *  and box properties (a round chip is a 34pt circle with a centered glyph),
  *  and RN cannot centre a glyph inside <Text> the way flexbox does. */
-function BlockText({ text, style, ctx, inherited, onPress, }) {
+function BlockText({ text, style, ctx, inherited, onPress, pressLabel, }) {
     const styleCtx = { ...ctx.style, fontSize: inherited.fontSize };
     // The block's own typography is folded into the inherited set first, so
     // em letter-spacing and unitless line-height resolve against whichever font
@@ -291,7 +291,7 @@ function BlockText({ text, style, ctx, inherited, onPress, }) {
     // wrapping a styled View would leave a pinned chip resolving its offsets
     // against a zero-sized parent.
     if (onPress) {
-        return (React.createElement(react_native_1.Pressable, { accessibilityRole: "button", accessibilityLabel: "Close", hitSlop: 8, onPress: onPress, style: (0, style_js_1.toViewStyle)(style, styleCtx) }, body));
+        return (React.createElement(react_native_1.Pressable, { accessibilityRole: "button", accessibilityLabel: pressLabel, hitSlop: 8, onPress: onPress, style: (0, style_js_1.toViewStyle)(style, styleCtx) }, body));
     }
     return React.createElement(react_native_1.View, { style: (0, style_js_1.toViewStyle)(style, styleCtx) }, body);
 }
@@ -330,27 +330,34 @@ function Carousel({ pages, autoAdvance, doc, }) {
                     setPage(Math.round(e.nativeEvent.contentOffset.x / size.width));
                 }
             } }, pages.map((node, i) => (React.createElement(react_native_1.View, { key: i, style: size }, node)))),
-        pages.length > 1 ? (React.createElement(react_native_1.View, { pointerEvents: "none", style: {
+        pages.length > 1 ? (React.createElement(Dots, { count: pages.length, active: page, doc: doc, style: { bottom: 8 } })) : null));
+}
+function Dots({ count, active, doc, style, }) {
+    return (React.createElement(react_native_1.View, { pointerEvents: "none", style: [
+            {
                 position: "absolute",
-                bottom: 8,
                 left: 0,
                 right: 0,
                 flexDirection: "row",
                 justifyContent: "center",
                 gap: 6,
-            } }, pages.map((_, i) => (React.createElement(react_native_1.View, { key: i, style: {
-                width: 6,
-                height: 6,
-                borderRadius: 3,
-                backgroundColor: i === page ? doc.accent : (0, color_js_1.withAlpha)(doc.textColor, 0.3),
-            } }))))) : null));
+            },
+            style,
+        ] }, Array.from({ length: count }, (_, i) => (React.createElement(react_native_1.View, { key: i, style: {
+            width: 6,
+            height: 6,
+            borderRadius: 3,
+            backgroundColor: i === active ? doc.accent : (0, color_js_1.withAlpha)(doc.textColor, 0.3),
+        } })))));
 }
-/** The press handler for a block the design marks as the close, or undefined
- *  when it is not one (or the host wired no dismissal). One helper so text,
- *  image and button blocks cannot drift on what "action: close" means. */
-function closePress(block, ctx) {
-    return block.action === "close" && ctx.onClose ? ctx.onClose : undefined;
+function actionPress(block, ctx) {
+    return block.action === "close" ? ctx.onClose : ctx.navigate(block.action);
 }
+const ACTION_LABEL = {
+    close: "Close",
+    next: "Next",
+    back: "Back",
+};
 /** Typography that is NOT inherited (decoration) — everything else already
  *  arrives through the inherited set. */
 function textOnly(s, ctx) {
@@ -475,7 +482,7 @@ function Block({ block, ctx, pkg, inherited, selection, }) {
     const size = text.fontSize;
     switch (block.type) {
         case "text":
-            return (React.createElement(BlockText, { text: (0, tags_js_1.resolveTags)(block.text, pkg, ctx.packages), style: style, ctx: ctx, inherited: inherited, onPress: closePress(block, ctx) }));
+            return (React.createElement(BlockText, { text: (0, tags_js_1.resolveTags)(block.text, pkg, ctx.packages), style: style, ctx: ctx, inherited: inherited, onPress: actionPress(block, ctx), pressLabel: block.action === "close" ? "Close" : undefined }));
         case "timer":
             return React.createElement(Timer, { block: block, style: style, ctx: ctx, inherited: inherited });
         case "toggle": {
@@ -506,12 +513,10 @@ function Block({ block, ctx, pkg, inherited, selection, }) {
                     s.aspectRatio !== undefined ||
                     (s.top !== undefined && s.bottom !== undefined) ||
                     s.flex !== undefined);
-            // An icon the design marks as the close (REV-252). Same rule as text:
-            // the whole box is the target, and the style lands on the Pressable so
-            // a pinned icon keeps its offsets.
-            const closeImage = image ? closePress(block, ctx) : undefined;
-            const ImageBox = closeImage ? react_native_1.Pressable : react_native_1.View;
-            return (React.createElement(ImageBox, { accessibilityRole: closeImage ? "button" : undefined, accessibilityLabel: closeImage ? "Close" : undefined, hitSlop: closeImage ? 8 : undefined, onPress: closeImage, style: [
+            const action = block.type === "image" ? block.action : undefined;
+            const imagePress = actionPress({ action }, ctx);
+            const ImageBox = imagePress ? react_native_1.Pressable : react_native_1.View;
+            return (React.createElement(ImageBox, { accessibilityRole: imagePress ? "button" : undefined, accessibilityLabel: imagePress && action ? ACTION_LABEL[action] : undefined, hitSlop: imagePress ? 8 : undefined, onPress: imagePress, style: [
                     sized ? null : { height: 160 },
                     { borderRadius: round ? 9999 : sized ? 0 : 16, overflow: "hidden", flexShrink: 0 },
                     view,
@@ -552,12 +557,13 @@ function Block({ block, ctx, pkg, inherited, selection, }) {
             // A button the design marks as the close dismisses instead of buying,
             // and takes no accent fill: the CTA must stay the one accented thing on
             // the screen, or a "Not now" competes with "Subscribe" for the eye.
-            const close = closePress(block, ctx);
+            const close = block.action === "close" ? ctx.onClose : undefined;
+            const navigates = block.action === "next" || block.action === "back";
             // A purchase in flight: the button keeps its box and fill, loses its
             // label to a spinner in the ink colour, and ignores taps. A close
             // button is never blocked — the user can always leave.
-            const busy = !close && ctx.loading;
-            return (React.createElement(react_native_1.Pressable, { accessibilityRole: "button", accessibilityState: { disabled: busy, busy }, disabled: busy, onPress: close ?? ctx.onPurchase, style: ({ pressed }) => [
+            const busy = !close && !navigates && ctx.loading;
+            return (React.createElement(react_native_1.Pressable, { accessibilityRole: "button", accessibilityState: { disabled: busy, busy }, disabled: busy, onPress: navigates ? actionPress(block, ctx) : (close ?? ctx.onPurchase), style: ({ pressed }) => [
                     {
                         backgroundColor: close ? "transparent" : doc.accent,
                         borderRadius: 12,
@@ -714,6 +720,13 @@ function RevnixBlockPaywall(props) {
     const doc = React.useMemo(() => (0, locale_js_1.localizeBlockDoc)(props.doc, props.locale ?? (0, locale_js_1.detectLocale)()), [props.doc, props.locale]);
     const [internalSelected, setInternalSelected] = React.useState(undefined);
     const [shownAt] = React.useState(Date.now);
+    const [screenIndex, setScreenIndex] = React.useState(0);
+    const [screenDoc, setScreenDoc] = React.useState(props.doc);
+    if (screenDoc !== props.doc) {
+        setScreenDoc(props.doc);
+        setScreenIndex(0);
+    }
+    const screen = (0, types_js_1.onboardingScreen)(doc, screenIndex);
     // Contract §1: host → own tap → design highlight → first package, each
     // only when the offering carries it.
     const selectedId = (0, selection_js_1.selectedPackageId)(packages, props.selectedPackageId, internalSelected, props.highlightPackageId);
@@ -749,6 +762,10 @@ function RevnixBlockPaywall(props) {
         onTerms: props.onTerms,
         onPrivacy: props.onPrivacy,
         onClose: props.onClose,
+        navigate: (action) => {
+            const to = (0, types_js_1.stepScreen)(doc, screenIndex, action);
+            return to === undefined ? undefined : () => setScreenIndex(to);
+        },
         footer: props.footer,
         heroImageUrl: props.heroImageUrl,
         gradient: props.gradient,
@@ -757,14 +774,14 @@ function RevnixBlockPaywall(props) {
         loading: props.loading === true,
         shownAt,
     };
-    const children = doc.blocks.map((block) => (React.createElement(Block, { key: block.id, block: block, ctx: ctx, pkg: packages.find((p) => p.packageId === selectedId) ?? packages[0], inherited: rootText })));
+    const children = screen.blocks.map((block) => (React.createElement(Block, { key: block.id, block: block, ctx: ctx, pkg: packages.find((p) => p.packageId === selectedId) ?? packages[0], inherited: rootText })));
     // REV-252: the renderer's own close, drawn only for a design that authors
     // none. Rendered as a sibling of the tree — outside the canvas scale — so
     // it keeps its tap size and its distance from the screen edge whatever the
     // device width does to the design.
     const safeAreaTop = props.safeAreaTop ??
         (react_native_1.Platform.OS === "android" ? (react_native_1.StatusBar.currentHeight ?? 0) : 0);
-    const fallbackClose = props.onClose && !(0, types_js_1.hasCloseAction)(doc.blocks) ? (React.createElement(FallbackClose, { doc: doc, onPress: props.onClose, safeAreaTop: safeAreaTop })) : null;
+    const fallbackClose = props.onClose && !(0, types_js_1.hasCloseAction)(screen.blocks) ? (React.createElement(FallbackClose, { doc: doc, onPress: props.onClose, safeAreaTop: safeAreaTop })) : null;
     const [width, setWidth] = React.useState(null);
     const [viewportHeight, setViewportHeight] = React.useState(null);
     if (doc.layout === "canvas") {
@@ -785,7 +802,7 @@ function RevnixBlockPaywall(props) {
         const canvasHeight = metrics?.scaledHeight ?? types_js_1.DESIGN_CANVAS.height;
         const left = metrics?.left ?? 0;
         return (React.createElement(ScreenBackground, { doc: doc, gradient: props.gradient, blur: props.blur, onDiagnostic: props.onDiagnostic, style: [{ flex: 1 }, props.style] },
-            React.createElement(react_native_1.ScrollView, { contentContainerStyle: { height: canvasHeight }, 
+            React.createElement(react_native_1.ScrollView, { key: screenIndex, contentContainerStyle: { height: canvasHeight }, 
                 // A designed screen never shows a scrollbar — the web preview has
                 // none, and in an RTL app the indicator lands on the left edge of
                 // the artwork. When nothing overflows, scrolling is off entirely so
@@ -809,15 +826,18 @@ function RevnixBlockPaywall(props) {
                                 { translateY: -((canvasHeight / scale) * (1 - scale)) / 2 },
                                 { scale },
                             ],
-                        } }, children))),
+                        } },
+                        children,
+                        screen.dots ? (React.createElement(Dots, { count: screen.dots.count, active: screen.dots.active, doc: doc, style: { top: 20, zIndex: 50 } })) : null))),
             fallbackClose));
     }
     return (React.createElement(ScreenBackground, { doc: doc, gradient: props.gradient, blur: props.blur, onDiagnostic: props.onDiagnostic, style: [{ flex: 1 }, props.style] },
-        React.createElement(react_native_1.ScrollView, { contentContainerStyle: {
+        React.createElement(react_native_1.ScrollView, { key: screenIndex, contentContainerStyle: {
                 gap: 12,
                 paddingHorizontal: 20,
                 paddingTop: 18,
                 paddingBottom: 30,
             }, showsVerticalScrollIndicator: false, alwaysBounceVertical: false, overScrollMode: "never" }, children),
+        screen.dots ? (React.createElement(Dots, { count: screen.dots.count, active: screen.dots.active, doc: doc, style: { top: 20 + safeAreaTop, zIndex: 50 } })) : null,
         fallbackClose));
 }

package/dist/ui/RevnixPaywall.js

@@ -76,7 +76,16 @@ function asBlockDoc(value) {
         typeof doc.textColor === "string" &&
         typeof doc.accent === "string" &&
         typeof doc.accentInk === "string"
-        ? doc
+        ? {
+            ...doc,
+            ...(doc.screens !== undefined
+                ? {
+                    screens: Array.isArray(doc.screens)
+                        ? doc.screens.filter((s) => Array.isArray(s) && s.length > 0)
+                        : [],
+                }
+                : {}),
+        }
         : null;
 }
 exports.DEFAULT_PAYWALL_THEME = {
@@ -289,7 +298,7 @@ function RevnixPaywall(props) {
     // arrives after a placeholder (or is swapped by an A/B assignment) would
     // otherwise crash on "rendered more hooks than during the previous render".
     const { config } = props;
-    const blocks = asBlockDoc(config.blocks);
+    const blocks = React.useMemo(() => asBlockDoc(config.blocks), [config.blocks]);
     // Both sinks fire when both are wired; nil when neither is, which is what
     // stops the renderer building a message nobody will read.
     const renderDiagnostic = client?.reportRenderDiagnostic || props.onDiagnostic

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.7.0";
+export declare const SDK_VERSION = "1.8.0";

package/dist/version.js

@@ -4,4 +4,4 @@ exports.SDK_VERSION = void 0;
 // L3: the single source of the SDK version inside src/. Must match
 // package.json "version" — version.test.ts fails the build when they drift
 // (they had: client.ts said 0.7.0 while the package shipped 0.9.0).
-exports.SDK_VERSION = "1.7.0";
+exports.SDK_VERSION = "1.8.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-revnix",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Revnix SDK for React, React Native & Next.js: purchase registration, entitlements, identity, and placements over the Revnix /v1 API.",
   "license": "MIT",
   "repository": {

package/src/blocks/locale.ts

@@ -193,6 +193,13 @@ export function localizeBlockDoc(
     ...doc,
     defaultLocale: chain[0],
     blocks: doc.blocks.map((b) => localizeBlock(b, lookup)),
+    ...(doc.screens
+      ? {
+          screens: doc.screens.map((screen) =>
+            screen.map((b) => localizeBlock(b, lookup))
+          ),
+        }
+      : {}),
   };
 }
 

package/src/blocks/types.ts

@@ -135,13 +135,15 @@ export interface BlockStyle {
  *  one. Ignored outside a package card — a root block is always drawn. */
 export type BlockVisibility = "selected" | "unselected";
 
-export type BlockAction = "close";
+/** `close` dismisses the paywall; `next`/`back` move between onboarding
+ *  screens and only appear inside `screens`. */
+export type BlockAction = "close" | "next" | "back";
 
 export interface TextBlock {
   id: string;
   type: "text";
   text: string;
-  /** Tapping this block dismisses the paywall. See BlockAction. */
+  /** What tapping this block does. See BlockAction. */
   action?: BlockAction;
   style?: BlockStyle;
   /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -159,7 +161,7 @@ export interface ImageBlock {
   shape?: "rect" | "circle";
   fit?: "cover" | "contain";
   placeholder?: string;
-  /** Tapping this block dismisses the paywall. See BlockAction. */
+  /** What tapping this block does. See BlockAction. */
   action?: BlockAction;
   style?: BlockStyle;
   /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -206,8 +208,9 @@ export interface ButtonBlock {
   id: string;
   type: "button";
   label: string;
-  /** `close` turns this button into a dismiss ("Not now") instead of the
-   *  purchase CTA, which is what a button means by default. */
+  /** `close` turns this button into a dismiss ("Not now"), and `next`/`back`
+   *  into onboarding navigation, instead of the purchase CTA, which is what a
+   *  button means by default. */
   action?: BlockAction;
   style?: BlockStyle;
   /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -356,6 +359,10 @@ export interface PaywallBlockDoc {
   accentInk: string;
   fontFamily?: string;
   blocks: PaywallBlock[];
+  /** Onboarding: intro screens shown in order before `blocks`, which stays
+   *  the last (purchase) screen. They share the doc's palette, layout and
+   *  locale table. Absent or empty = `blocks` alone. */
+  screens?: PaywallBlock[][];
   /** REV-271: the language the blocks' own copy is written in. Absent = "en".
    *  Never a key in a stored doc's `locales` — the tree IS that language's
    *  version. A localized copy names the language it was localized to. */
@@ -399,3 +406,26 @@ export function hasCloseAction(blocks: PaywallBlock[]): boolean {
           b.action === "close"
   );
 }
+
+export function onboardingScreen(
+  doc: PaywallBlockDoc,
+  index: number
+): { blocks: PaywallBlock[]; dots?: { count: number; active: number } } {
+  const intro = doc.screens?.[index];
+  if (intro === undefined) return { blocks: doc.blocks };
+  return {
+    blocks: intro,
+    dots: { count: doc.screens!.length + 1, active: index },
+  };
+}
+
+export function stepScreen(
+  doc: PaywallBlockDoc,
+  index: number,
+  action: BlockAction | undefined
+): number | undefined {
+  if (index >= (doc.screens?.length ?? 0)) return undefined;
+  if (action === "next") return index + 1;
+  if (action === "back" && index > 0) return index - 1;
+  return undefined;
+}

package/src/ui/RevnixBlockPaywall.tsx

@@ -74,6 +74,9 @@ import type { SelectionContext } from "../blocks/selection.js";
 import {
   DESIGN_CANVAS,
   hasCloseAction,
+  onboardingScreen,
+  stepScreen,
+  type BlockAction,
   type BlockStyle,
   type PaywallBlock,
   type PaywallBlockDoc,
@@ -600,6 +603,7 @@ interface RenderContext {
   onTerms?: () => void;
   onPrivacy?: () => void;
   onClose?: () => void;
+  navigate: (action: BlockAction | undefined) => (() => void) | undefined;
   footer?: { termsUrl?: string; privacyUrl?: string };
   heroImageUrl?: string;
   gradient?: RevnixGradientComponent;
@@ -622,13 +626,14 @@ function BlockText({
   ctx,
   inherited,
   onPress,
+  pressLabel,
 }: {
   text: string;
   style: BlockStyle | undefined;
   ctx: RenderContext;
   inherited: InheritedText;
-  /** Set when the design marks this element as the close (REV-252). */
   onPress?: () => void;
+  pressLabel?: string;
 }) {
   const styleCtx = { ...ctx.style, fontSize: inherited.fontSize };
   // The block's own typography is folded into the inherited set first, so
@@ -661,7 +666,7 @@ function BlockText({
     return (
       <Pressable
         accessibilityRole="button"
-        accessibilityLabel="Close"
+        accessibilityLabel={pressLabel}
         hitSlop={8}
         onPress={onPress}
         style={toViewStyle(style, styleCtx)}
@@ -745,46 +750,67 @@ function Carousel({
         ))}
       </ScrollView>
       {pages.length > 1 ? (
+        <Dots count={pages.length} active={page} doc={doc} style={{ bottom: 8 }} />
+      ) : null}
+    </View>
+  );
+}
+
+function Dots({
+  count,
+  active,
+  doc,
+  style,
+}: {
+  count: number;
+  active: number;
+  doc: PaywallBlockDoc;
+  style: ViewStyle;
+}) {
+  return (
+    <View
+      pointerEvents="none"
+      style={[
+        {
+          position: "absolute",
+          left: 0,
+          right: 0,
+          flexDirection: "row",
+          justifyContent: "center",
+          gap: 6,
+        },
+        style,
+      ]}
+    >
+      {Array.from({ length: count }, (_, i) => (
         <View
-          pointerEvents="none"
+          key={i}
           style={{
-            position: "absolute",
-            bottom: 8,
-            left: 0,
-            right: 0,
-            flexDirection: "row",
-            justifyContent: "center",
-            gap: 6,
+            width: 6,
+            height: 6,
+            borderRadius: 3,
+            backgroundColor:
+              i === active ? doc.accent : withAlpha(doc.textColor, 0.3),
           }}
-        >
-          {pages.map((_, i) => (
-            <View
-              key={i}
-              style={{
-                width: 6,
-                height: 6,
-                borderRadius: 3,
-                backgroundColor:
-                  i === page ? doc.accent : withAlpha(doc.textColor, 0.3),
-              }}
-            />
-          ))}
-        </View>
-      ) : null}
+        />
+      ))}
     </View>
   );
 }
 
-/** The press handler for a block the design marks as the close, or undefined
- *  when it is not one (or the host wired no dismissal). One helper so text,
- *  image and button blocks cannot drift on what "action: close" means. */
-function closePress(
-  block: { action?: "close" },
+function actionPress(
+  block: { action?: BlockAction },
   ctx: RenderContext
 ): (() => void) | undefined {
-  return block.action === "close" && ctx.onClose ? ctx.onClose : undefined;
+  return block.action === "close" ? ctx.onClose : ctx.navigate(block.action);
 }
 
+const ACTION_LABEL: Record<BlockAction, string> = {
+  close: "Close",
+  next: "Next",
+  back: "Back",
+};
+
 /** Typography that is NOT inherited (decoration) — everything else already
  *  arrives through the inherited set. */
 function textOnly(s: BlockStyle | undefined, ctx: StyleContext) {
@@ -983,7 +1009,8 @@ function Block({
           style={style}
           ctx={ctx}
           inherited={inherited}
-          onPress={closePress(block, ctx)}
+          onPress={actionPress(block, ctx)}
+          pressLabel={block.action === "close" ? "Close" : undefined}
         />
       );
 
@@ -1039,17 +1066,17 @@ function Block({
           s.aspectRatio !== undefined ||
           (s.top !== undefined && s.bottom !== undefined) ||
           s.flex !== undefined);
-      // An icon the design marks as the close (REV-252). Same rule as text:
-      // the whole box is the target, and the style lands on the Pressable so
-      // a pinned icon keeps its offsets.
-      const closeImage = image ? closePress(block, ctx) : undefined;
-      const ImageBox = closeImage ? Pressable : View;
+      const action = block.type === "image" ? block.action : undefined;
+      const imagePress = actionPress({ action }, ctx);
+      const ImageBox = imagePress ? Pressable : View;
       return (
         <ImageBox
-          accessibilityRole={closeImage ? "button" : undefined}
-          accessibilityLabel={closeImage ? "Close" : undefined}
-          hitSlop={closeImage ? 8 : undefined}
-          onPress={closeImage}
+          accessibilityRole={imagePress ? "button" : undefined}
+          accessibilityLabel={
+            imagePress && action ? ACTION_LABEL[action] : undefined
+          }
+          hitSlop={imagePress ? 8 : undefined}
+          onPress={imagePress}
           style={[
             sized ? null : { height: 160 },
             { borderRadius: round ? 9999 : sized ? 0 : 16, overflow: "hidden", flexShrink: 0 },
@@ -1130,17 +1157,18 @@ function Block({
       // A button the design marks as the close dismisses instead of buying,
       // and takes no accent fill: the CTA must stay the one accented thing on
       // the screen, or a "Not now" competes with "Subscribe" for the eye.
-      const close = closePress(block, ctx);
+      const close = block.action === "close" ? ctx.onClose : undefined;
+      const navigates = block.action === "next" || block.action === "back";
       // A purchase in flight: the button keeps its box and fill, loses its
       // label to a spinner in the ink colour, and ignores taps. A close
       // button is never blocked — the user can always leave.
-      const busy = !close && ctx.loading;
+      const busy = !close && !navigates && ctx.loading;
       return (
         <Pressable
           accessibilityRole="button"
           accessibilityState={{ disabled: busy, busy }}
           disabled={busy}
-          onPress={close ?? ctx.onPurchase}
+          onPress={navigates ? actionPress(block, ctx) : (close ?? ctx.onPurchase)}
           style={({ pressed }) => [
             {
               backgroundColor: close ? "transparent" : doc.accent,
@@ -1408,6 +1436,13 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
     string | undefined
   >(undefined);
   const [shownAt] = React.useState(Date.now);
+  const [screenIndex, setScreenIndex] = React.useState(0);
+  const [screenDoc, setScreenDoc] = React.useState(props.doc);
+  if (screenDoc !== props.doc) {
+    setScreenDoc(props.doc);
+    setScreenIndex(0);
+  }
+  const screen = onboardingScreen(doc, screenIndex);
   // Contract §1: host → own tap → design highlight → first package, each
   // only when the offering carries it.
   const selectedId = selectedPackageId(
@@ -1451,6 +1486,10 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
     onTerms: props.onTerms,
     onPrivacy: props.onPrivacy,
     onClose: props.onClose,
+    navigate: (action) => {
+      const to = stepScreen(doc, screenIndex, action);
+      return to === undefined ? undefined : () => setScreenIndex(to);
+    },
     footer: props.footer,
     heroImageUrl: props.heroImageUrl,
     gradient: props.gradient,
@@ -1460,7 +1499,7 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
     shownAt,
   };
 
-  const children = doc.blocks.map((block) => (
+  const children = screen.blocks.map((block) => (
     <Block
       key={block.id}
       block={block}
@@ -1478,7 +1517,7 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
     props.safeAreaTop ??
     (Platform.OS === "android" ? (StatusBar.currentHeight ?? 0) : 0);
   const fallbackClose =
-    props.onClose && !hasCloseAction(doc.blocks) ? (
+    props.onClose && !hasCloseAction(screen.blocks) ? (
       <FallbackClose
         doc={doc}
         onPress={props.onClose}
@@ -1518,6 +1557,7 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
         style={[{ flex: 1 }, props.style]}
       >
         <ScrollView
+          key={screenIndex}
           contentContainerStyle={{ height: canvasHeight }}
           // A designed screen never shows a scrollbar — the web preview has
           // none, and in an RTL app the indicator lands on the left edge of
@@ -1554,6 +1594,14 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
               }}
             >
               {children}
+              {screen.dots ? (
+                <Dots
+                  count={screen.dots.count}
+                  active={screen.dots.active}
+                  doc={doc}
+                  style={{ top: 20, zIndex: 50 }}
+                />
+              ) : null}
             </View>
           </View>
         </ScrollView>
@@ -1571,6 +1619,7 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
       style={[{ flex: 1 }, props.style]}
     >
       <ScrollView
+        key={screenIndex}
         contentContainerStyle={{
           gap: 12,
           paddingHorizontal: 20,
@@ -1583,6 +1632,14 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
       >
         {children}
       </ScrollView>
+      {screen.dots ? (
+        <Dots
+          count={screen.dots.count}
+          active={screen.dots.active}
+          doc={doc}
+          style={{ top: 20 + safeAreaTop, zIndex: 50 }}
+        />
+      ) : null}
       {fallbackClose}
     </ScreenBackground>
   );

package/src/ui/RevnixPaywall.tsx

@@ -65,7 +65,16 @@ function asBlockDoc(value: unknown): PaywallBlockDoc | null {
     typeof doc.textColor === "string" &&
     typeof doc.accent === "string" &&
     typeof doc.accentInk === "string"
-    ? (doc as PaywallBlockDoc)
+    ? {
+        ...(doc as PaywallBlockDoc),
+        ...(doc.screens !== undefined
+          ? {
+              screens: Array.isArray(doc.screens)
+                ? doc.screens.filter((s) => Array.isArray(s) && s.length > 0)
+                : [],
+            }
+          : {}),
+      }
     : null;
 }
 
@@ -480,7 +489,7 @@ export function RevnixPaywall(props: RevnixPaywallProps) {
   // arrives after a placeholder (or is swapped by an A/B assignment) would
   // otherwise crash on "rendered more hooks than during the previous render".
   const { config } = props;
-  const blocks = asBlockDoc(config.blocks);
+  const blocks = React.useMemo(() => asBlockDoc(config.blocks), [config.blocks]);
   // Both sinks fire when both are wired; nil when neither is, which is what
   // stops the renderer building a message nobody will read.
   const renderDiagnostic =

package/src/version.ts

@@ -1,4 +1,4 @@
 // L3: the single source of the SDK version inside src/. Must match
 // package.json "version" — version.test.ts fails the build when they drift
 // (they had: client.ts said 0.7.0 while the package shipped 0.9.0).
-export const SDK_VERSION = "1.7.0";
+export const SDK_VERSION = "1.8.0";