luna-stage

Stage system and showcase components for the L.U.N.A project. Atomic components for rendering Lynx bundles into a device shell / stage in the browser.

Use luna-stage when you need a single-frame preview (Stage + LunaLynxStage) or motion-enhanced presentation (MotionStage, etc.). For multi-stage orchestration and Studio-level layout, see @dugyu/luna-studio.

Installation

pnpm i @dugyu/luna-stage

Peer dependencies — install in your application:

pnpm i react

For Lynx rendering (LynxStage / LunaLynxStage), install the Lynx Web runtime:

pnpm i @lynx-js/web-core

For motion capabilities, install motion:

pnpm i motion

Entry Points

| Import path | Requires motion | Requires @lynx-js/web-core | Use when | | -------------------------- | ----------------- | ---------------------------- | --------------------------------------------------------- | | @dugyu/luna-stage | No | No | Static device frame + shared hooks | | @dugyu/luna-stage/lynx | No | Yes | Lynx bundle rendering (LynxStage / LunaLynxStage) | | @dugyu/luna-stage/motion | Yes | No | Animated transitions + perspective camera (MotionStage) |

Concepts

Device Frame Model

• baseWidth / baseHeight define the design baseline (default 375×812), not the container size
• The component renders at baseWidth×baseHeight and uses CSS transform: scale() to fit into the container
• Two visual layers: outline (decorative border, simulates device thickness) and frame (content area with clip-path)
• The root element is a zero-size anchor (w-0 h-0 overflow-visible) — the device frame extends outward from it

Fit System

• contain — scales down to fit fully inside the container (no cropping)
• cover — scales up to fully cover the container (may crop)
• alignX / alignY — control which part of the frame is preserved when cover crops. Physical directions: left | center | right / top | center | bottom
• fitProgress (motion only) — continuous 0→1 interpolation between contain and cover, driven by a spring

Camera Model (MotionStage only)

The transform pipeline operates in two independent spaces:

Screen space

• fit / fitProgress — container-driven passive scaling
• zoom — user-controlled active scaling, applied on top of fit
• panX / panY — screen-space translation in pixels, applied after all scaling

World space

• world — 3D position of the frame { x, y, z }. Follows the CSS/OpenGL convention: +Z points toward the viewer.
• focalLength — perspective intensity. When > 0, enables perspective projection. When 0 or omitted, orthographic.
• world.x/y are projected into screen space before being composited with panX/panY. The spring animates the combined screen-space value.

Final scale = lerpFitScale(contain, cover, fitSpring) × zoom × depthScale

Final translation = world.xy × depthScale + panXY

Quick Start

Single-frame preview with LunaLynxStage

import { Stage } from '@dugyu/luna-stage';
import { LunaLynxStage } from '@dugyu/luna-stage/lynx';

export default function Preview() {
  return (
    <Stage>
      <LunaLynxStage
        entry='my-component'
        bundleRoot='/bundles/'
        lunaTheme='lunaris-dark'
      />
    </Stage>
  );
}

Default bundle URL convention: ${bundleRoot}${entry}.web.bundle

Override it with resolveBundleSrc when your host uses a different naming rule.

bundleRoot is normalized internally to always end with a trailing slash before URL resolution. This means callers may pass either '/bundles' or '/bundles/', and resolveBundleSrc will always receive the normalized value.

lunaTheme injects LUNA design token globals into the Lynx runtime.

Without LUNA theming

Use LynxStage directly when you don't need LUNA global props forwarded:

import { Stage } from '@dugyu/luna-stage';
import { LynxStage } from '@dugyu/luna-stage/lynx';

<Stage>
  <LynxStage entry='my-component' bundleRoot='/bundles/' />
</Stage>;

Standalone LynxStage

LynxStage can be used independently of the Stage system if you just want to render a Lynx view in a DOM container:

import { LynxStage } from '@dugyu/luna-stage/lynx';

export default function StandaloneView() {
  return (
    <div className='w-full h-screen'>
      <LynxStage entry='my-component' bundleRoot='/bundles/' />
    </div>
  );
}

API

Stage

Static device frame. Reads container size from StageContainer context if present, otherwise falls back to baseWidth/baseHeight.

Stage can be used in three ways:

Standalone — renders at design baseline size:

<Stage>
  <YourContent />
</Stage>;

Manual size — explicit container dimensions:

<Stage width={390} height={844}>
  <YourContent />
</Stage>;

With StageContainer — auto-measures the container:

<StageContainer className='w-full h-full'>
  <Stage>
    <YourContent />
  </Stage>
</StageContainer>;

| Prop | Type | Default | Description | | ------------ | ------------------------------- | ----------- | --------------------------------------------------------------- | | baseWidth | number | 375 | Design baseline width in pixels | | baseHeight | number | 812 | Design baseline height in pixels | | width | number | — | Container width. Falls back to StageContainer → baseWidth | | height | number | — | Container height. Falls back to StageContainer → baseHeight | | fit | 'contain' \| 'cover' | 'contain' | Fit mode | | alignX | 'left' \| 'center' \| 'right' | 'center' | Horizontal crop anchor | | alignY | 'top' \| 'center' \| 'bottom' | 'center' | Vertical crop anchor | | zoom | number | 1 | Additional zoom factor on top of fit | | panX | number | 0 | Screen-space translation along X (px) | | panY | number | 0 | Screen-space translation along Y (px) | | className | string | — | Applied to the outline layer | | style | CSSProperties | — | Applied to the outline layer | | onClick | MouseEventHandler | — | — |

StageContainer

Measures its own DOM size via ResizeObserver and provides width/height to child Stage components via context.

| Prop | Type | Default | Description | | ---------------- | -------- | ------- | ----------------------------- | | fallbackWidth | number | 0 | Used before first measurement | | fallbackHeight | number | 0 | Used before first measurement |

LynxStage

Core component for rendering Lynx bundles into a DOM container.

| Prop | Type | Default | Description | | --------------------- | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | entry | string | — | Entry name for the Lynx bundle. | | bundleRoot | string | '/' | Resource root used with entry to locate the bundle. Normalized to always end with / before URL resolution. | | resolveBundleSrc | function | — | Optional hook for overriding how the final bundle URL is built. Receives the normalized bundleRoot (always ends with /). | | globalProps | Record<string, unknown> | — | Global props to inject into the Lynx runtime. | | groupId | number | 7 | Shared Lynx worker group ID. | | onNativeModulesCall | function | — | Callback for native module calls from Lynx runtime. | | onReady | function | — | Callback when the view has rendered successfully. | | onError | function | — | Callback when an error occurs during loading or rendering. |

LunaLynxStage

Extends LynxStage with LUNA theme properties.

| Prop | Type | Default | Description | | ------------------ | ------------------------- | -------------- | --------------------------------------------- | | lunaTheme | LunaThemeKey | 'luna-light' | LUNA theme key (e.g. 'luna-light'). | | extraGlobalProps | Record<string, unknown> | — | Additional global props. | | (others) | | | All LynxStage props (except globalProps). |

MotionStage

Animated device frame. Extends Stage's base props with spring-driven transitions and a perspective camera model.

| Prop | Type | Default | Description | | ---------------- | ---------------------- | ------------------- | ----------------------------------------------------------------------------------- | | width | MotionValue<number> | — | Reactive container width | | height | MotionValue<number> | — | Reactive container height | | fit | 'contain' \| 'cover' | 'contain' | Fit mode (ignored when fitProgress is set) | | fitProgress | number | — | 0–1 blend between contain and cover | | zoom | number | 1 | Additional zoom factor | | panX | number | 0 | Screen-space translation along X (px) | | panY | number | 0 | Screen-space translation along Y (px) | | world | { x?, y?, z? } | { x:0, y:0, z:0 } | World-space position. +Z toward viewer. | | focalLength | number | — | Perspective focal length (px). Omit for orthographic. | | fitTransition | SpringOptions | — | Spring for fit / fitProgress | | zoomTransition | SpringOptions | — | Spring for zoom | | panTransition | SpringOptions | — | Spring for the combined screen-space translation (panX/Y + projected world.x/y) | | maskColor | string | 'transparent' | Overlay mask color | | maskOpacity | number | 0 | Overlay mask opacity, animated |

MotionStageContainer

Motion-aware equivalent of StageContainer. Provides MotionValue<number> width/height to child MotionStage components via context. Handles layout animations and extracts the parent scale from transformTemplate to keep the visual size accurate during transitions.

MotionPresentation

A zero-size anchor element (4px × 4px, overflow-visible) that wraps AnimatePresence propagate.

Use when: items are dynamically added/removed and need mount/unmount animations.

Skip when: components are always mounted, or you only need state transition animations.

Usage Examples

Motion: no mount/unmount

import { MotionStage, MotionStageContainer } from '@dugyu/luna-stage/motion';

<MotionStageContainer className='w-full h-full'>
  <MotionStage fitProgress={0} zoom={1.2}>
    <YourContent />
  </MotionStage>
</MotionStageContainer>;

Motion: with mount/unmount animations

import {
  MotionStage,
  MotionStageContainer,
  MotionPresentation,
} from '@dugyu/luna-stage/motion';

const variants = {
  initial: { opacity: 0, x: -300 },
  animate: { opacity: 1, x: 0 },
  exit: { opacity: 0, x: 300 },
};

<AnimatePresence>
  {items.map(item => (
    <MotionStageContainer key={item.id} layoutId={item.id}>
      <MotionPresentation
        variants={variants}
        initial='initial'
        animate='animate'
        exit='exit'
      >
        <MotionStage world={item.world} focalLength={500}>
          <YourContent />
        </MotionStage>
      </MotionPresentation>
    </MotionStageContainer>
  ))}
</AnimatePresence>;

Perspective carousel

Arrange frames along a circular arc. +Z is toward the viewer, so objects at z < 0 appear further away:

const theta = (index - mid) * (Math.PI / 9); // 20° apart
const world = {
  x: Math.sin(theta) * radius,
  z: -Math.cos(theta) * radius, // negative = further from viewer
};

<MotionStage world={world} focalLength={500}>
  <YourContent />
</MotionStage>;

Orthographic compare layout

Omit focalLength (or set to 0) — all frames render at equal scale regardless of world.z:

<MotionStage world={{ x: offset, y: 0, z: 0 }}>
  <YourContent />
</MotionStage>;

Component Table

| Component | Entry point | Description | | ---------------------- | ----------- | ----------------------------------------------------- | | Stage | . | Static device frame | | StageContainer | . | Auto-measures container, provides size via context | | LynxStage | ./lynx | Core Lynx bundle renderer (no LUNA globals) | | LunaLynxStage | ./lynx | LynxStage + LUNA theme prop injection | | MotionStage | ./motion | Animated device frame with perspective camera | | MotionStageContainer | ./motion | Layout animation wrapper, provides MotionValue size | | MotionPresentation | ./motion | Mount/unmount transition orchestrator |

Hooks

| Export | Entry point | Description | | --------------------------- | ----------- | -------------------------------------------------- | | useEventCallback | . | Stable callback that always calls the latest fn | | useIsClient | . | SSR-safe client-side mount detection | | useContainerResize | . | Observes container dimensions via ResizeObserver | | useMergedRefs | . | Merges multiple refs onto a single element | | useIsomorphicLayoutEffect | . | SSR-safe useLayoutEffect | | useLynxStage | ./lynx | Core hook for managing Lynx runtime and lifecycle |

SSR / SSG Notes

LynxStage and LunaLynxStage are client-only. They render null on the server and mount only after hydration.

Bundle & Asset Conventions

• By default, bundle files follow the naming pattern *.web.bundle
• bundleRoot is normalized to a trailing slash by the default resolver
• Default resolved URL: ${bundleRoot}${entry}.web.bundle
• Use resolveBundleSrc when your host needs a different file naming rule or full URL composition

Transform Utilities

The functions in src/utils/transform.ts are zero-dependency pure functions, safe to copy into other projects.

| Function | Description | | ---------------------------------------- | ----------------------------------------------------- | | computeScaleRange(input) | Returns { contain, cover } scale factors | | lerpFitScale(range, t) | Interpolates between contain and cover | | computeFrameOffset(input) | Returns { offsetX, offsetY } for CSS transform | | computeDepthScale(focalLength, worldZ) | Perspective depth scale f / (f - z) | | computeScreenTranslation(input) | Projects world XY + screen pan into final translation |

To integrate fit/scale into a lynx-view container: copy computeScaleRange, lerpFitScale, and computeFrameOffset. Fix lynx-view at baseWidth × baseHeight, apply the computed transform via CSS, and pass design-baseline pixel dimensions to browserConfig rather than the container's measured size.