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.

Contents

• Installation
• Entry Points
• Concepts
• Quick Start
• API
• Usage Examples
• SSR / SSG Notes
• Transform Utilities

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

Concepts

Device Frame Model

• baseWidth / baseHeight define the design baseline (default 375×812), not the viewport size.
• The frame renders at its base dimensions and uses CSS transform: scale() to fit into the viewport.
• Two visual layers: outline (decorative border, simulates device thickness) and frame (content area with clip-path).
• Stage only: an absolutely-positioned 0×0 anchor sits inside the viewport at the placeX/placeY location; the outline and frame are transformed around this anchor.

Fit System

• contain — scales down to fit fully inside the viewport (no cropping).
• cover — scales up to fully cover the viewport (may crop).
• alignX / alignY — alignment of the frame within the viewport. In cover mode also determines which part of the frame is preserved when cropped. Physical directions: left | center | right / top | center | bottom.
• placeX / placeY (Stage only) — placement of the anchor within the viewport, decoupled from alignX/Y. Defaults to match alignX/Y for object-position-like semantics. Override only when you want the frame's internal alignment to differ from its viewport position (rare).
• 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 — viewport-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, StageContainer } from '@dugyu/luna-stage';
import { LunaLynxStage } from '@dugyu/luna-stage/lynx';

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

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, StageContainer } from '@dugyu/luna-stage';
import { LynxStage } from '@dugyu/luna-stage/lynx';

<StageContainer className='w-full h-screen'>
  <Stage>
    <LynxStage entry='my-component' bundleRoot='/bundles/' />
  </Stage>
</StageContainer>;

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 viewport size from StageContainer context if present, otherwise falls back to baseWidth/baseHeight.

Stage supports two ways to determine its viewport size:

Auto-fit to parent (recommended) — wrap in StageContainer so the viewport auto-measures and the frame fits to it:

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

Explicit viewport size — pass width / height directly to Stage. Useful for fixed-size previews, server-rendered layouts, or anywhere you'd rather not add a measuring wrapper:

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

Note: Wrapping Stage in a sized <div> without StageContainer won't make the frame fit the div — Stage has no way to read the div's size and will fall back to baseWidth × baseHeight. Use StageContainer or pass width/height directly.

Props

StageContainer

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

Add padding, border, or layout styling to StageContainer freely — the measured content box is what Stage fits to, so padding works as expected visual margin around the frame.

Avoid setting transform, filter, perspective, backdrop-filter, or contain: paint/layout/strict on StageContainer — these establish a containing block that traps position: fixed descendants inside the stage.

Props

Inherits all <div> HTML attributes (className, style, etc.).

LynxStage

Core component for rendering Lynx bundles into a DOM container.

LunaLynxStage

Extends LynxStage with LUNA theme properties.

MotionStage

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

MotionStage is recommended inside MotionStageContainer for responsive sizing and layout animations. When rendered standalone it falls back to its baseline size, and you can override sizing explicitly via the width / height MotionValue<number> props.

Props

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.

Must be used as a child of <AnimatePresence> for mount/unmount animations to work.

Props

Inherits all motion.div props (except transformTemplate, which is used internally).

MotionPresentation

A zero-size flex-centered anchor that wraps AnimatePresence propagate for descendant mount/unmount animations.

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.

Inherits all motion.div props (variants, initial, animate, exit, transition, etc.).

Usage Examples

Motion: no mount/unmount

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

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

Motion: with mount/unmount animations

import { AnimatePresence } from 'motion/react';
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 mode='popLayout'>
  {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

Hooks

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.

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.