` size and fit/scale. Falls back to `StageContainer` → `baseWidth`. |\n| `height` | `number` | — | Explicit viewport size. Drives both rendered `
` size and fit/scale. Falls back to `StageContainer` → `baseHeight`. |\n| `fit` | `'contain' \\| 'cover'` | `'contain'` | Fit mode. |\n| `alignX` | `'left' \\| 'center' \\| 'right'` | `'center'` | Horizontal alignment of frame within viewport. In `cover` mode also determines crop anchor. |\n| `alignY` | `'top' \\| 'center' \\| 'bottom'` | `'center'` | Vertical alignment of frame within viewport. In `cover` mode also determines crop anchor. |\n| `placeX` | `'left' \\| 'center' \\| 'right'` | `alignX` | Horizontal placement of the internal anchor within the viewport. Override to decouple placement from alignment. |\n| `placeY` | `'top' \\| 'center' \\| 'bottom'` | `alignY` | Vertical placement of the internal anchor within the viewport. Override to decouple placement from alignment. |\n| `zoom` | `number` | `1` | Additional zoom factor on top of fit. |\n| `panX` | `number` | `0` | Screen-space translation along X (px). |\n| `panY` | `number` | `0` | Screen-space translation along Y (px). |\n| `className` | `string` | — | Applied to the outline layer. |\n| `style` | `CSSProperties` | — | Applied to the outline layer. |\n| `onClick` | `MouseEventHandler` | — | — |\n\n### `StageContainer`\n\nMeasures its own DOM size via `ResizeObserver` and provides width/height to child `Stage` components via context.\n\nAdd 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.\n\nAvoid 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.\n\n#### Props\n\n| Prop | Type | Default | Description |\n| ---------------- | -------- | ------- | ------------------------------ |\n| `fallbackWidth` | `number` | `0` | Used before first measurement. |\n| `fallbackHeight` | `number` | `0` | Used before first measurement. |\n\nInherits all `
` HTML attributes (`className`, `style`, etc.).\n\n### `LynxStage`\n\nCore component for rendering Lynx bundles into a DOM container.\n\n| Prop | Type | Default | Description |\n| --------------------- | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `entry` | `string` | — | Entry name for the Lynx bundle. |\n| `bundleRoot` | `string` | `'/'` | Resource root used with `entry` to locate the bundle. Normalized to always end with `/` before URL resolution. |\n| `resolveBundleSrc` | `function` | — | Optional hook for overriding how the final bundle URL is built. Receives the normalized `bundleRoot` (always ends with `/`). |\n| `globalProps` | `Record
` | — | Global props to inject into the Lynx runtime. |\n| `groupId` | `number` | `7` | Shared Lynx worker group ID. |\n| `onNativeModulesCall` | `function` | — | Callback for native module calls from Lynx runtime. |\n| `onReady` | `function` | — | Callback when the view has rendered successfully. |\n| `onError` | `function` | — | Callback when an error occurs during loading or rendering. |\n\n### `LunaLynxStage`\n\nExtends `LynxStage` with LUNA theme properties.\n\n| Prop | Type | Default | Description |\n| ------------------ | ------------------------- | -------------- | --------------------------------------------- |\n| `lunaTheme` | `LunaThemeKey` | `'luna-light'` | LUNA theme key (e.g. `'luna-light'`). |\n| `extraGlobalProps` | `Record` | — | Additional global props. |\n| _(others)_ | | | All `LynxStage` props (except `globalProps`). |\n\n### `MotionStage`\n\nAnimated device frame. Extends `Stage`'s base props with spring-driven transitions and a perspective camera model.\n\n`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` props.\n\n#### Props\n\n| Prop | Type | Default | Description |\n| -------------------- | ------------------------------- | ------------------- | -------------------------------------------------------------------------------- |\n| `baseWidth` | `number` | `375` | Design baseline width in pixels. |\n| `baseHeight` | `number` | `812` | Design baseline height in pixels. |\n| `width` | `MotionValue` | — | Override the viewport width (from context). For advanced cases. |\n| `height` | `MotionValue` | — | Override the viewport height (from context). For advanced cases. |\n| `fit` | `'contain' \\| 'cover'` | `'contain'` | Fit mode. Ignored when `fitProgress` is set. |\n| `fitProgress` | `number` | — | `0–1` blend between contain and cover, driven by a spring. |\n| `zoom` | `number` | `1` | Additional zoom factor. |\n| `panX` | `number` | `0` | Screen-space translation along X (px). |\n| `panY` | `number` | `0` | Screen-space translation along Y (px). |\n| `world` | `{ x?, y?, z? }` | `{ x:0, y:0, z:0 }` | World-space position. `+Z` toward viewer. |\n| `focalLength` | `number` | — | Perspective focal length (px). Omit for orthographic. |\n| `alignX` | `'left' \\| 'center' \\| 'right'` | `'center'` | Horizontal alignment of frame within viewport. |\n| `alignY` | `'top' \\| 'center' \\| 'bottom'` | `'center'` | Vertical alignment of frame within viewport. |\n| `fitTransition` | `SpringOptions` | — | Spring for `fit` / `fitProgress`. |\n| `zoomTransition` | `SpringOptions` | — | Spring for `zoom`. |\n| `panTransition` | `SpringOptions` | — | Spring for combined screen-space translation (`panX/Y` + projected `world.x/y`). |\n| `maskColor` | `string` | `'transparent'` | Overlay mask color. |\n| `maskOpacity` | `number` | `0` | Overlay mask opacity (animated). |\n| `contentInteractive` | `boolean` | `false` | Whether the frame's children receive pointer events. |\n| `className` | `string` | — | Applied to the outline layer. |\n| `style` | `MotionStyle` | — | Applied to the outline layer. |\n\n### `MotionStageContainer`\n\nMotion-aware equivalent of `StageContainer`. Provides `MotionValue` 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.\n\nMust be used as a child of `` for mount/unmount animations to work.\n\n#### Props\n\n| Prop | Type | Default | Description |\n| --------------------------- | -------------------- | ------- | ----------------------------------------------------------------------- |\n| `layoutId` | `string` | — | Unique ID for layout animation matching across mount/unmount. Required. |\n| `onLayoutMeasure` | `(box: Box) => void` | — | Forwarded from `motion`. Called when layout box is measured. |\n| `onLayoutAnimationStart` | `() => void` | — | Forwarded from `motion`. Called when layout animation starts. |\n| `onLayoutAnimationComplete` | `() => void` | — | Forwarded from `motion`. Called when layout animation completes. |\n\nInherits all `motion.div` props (except `transformTemplate`, which is used internally).\n\n### `MotionPresentation`\n\nA zero-size flex-centered anchor that wraps `AnimatePresence propagate` for descendant mount/unmount animations.\n\n**Use when:** items are dynamically added/removed and need mount/unmount animations.\n\n**Skip when:** components are always mounted, or you only need state transition animations.\n\nInherits all `motion.div` props (`variants`, `initial`, `animate`, `exit`, `transition`, etc.).\n\n## Usage Examples\n\n### Motion: no mount/unmount\n\n```tsx\nimport { MotionStage, MotionStageContainer } from '@dugyu/luna-stage/motion';\n\n\n \n \n \n;\n```\n\n### Motion: with mount/unmount animations\n\n```tsx\nimport { AnimatePresence } from 'motion/react';\nimport {\n MotionStage,\n MotionStageContainer,\n MotionPresentation,\n} from '@dugyu/luna-stage/motion';\n\nconst variants = {\n initial: { opacity: 0, x: -300 },\n animate: { opacity: 1, x: 0 },\n exit: { opacity: 0, x: 300 },\n};\n\n\n {items.map(item => (\n \n \n \n \n \n \n \n ))}\n;\n```\n\n### Perspective carousel\n\nArrange frames along a circular arc. `+Z` is toward the viewer, so objects at `z < 0` appear further away:\n\n```tsx\nconst theta = (index - mid) * (Math.PI / 9); // 20° apart\nconst world = {\n x: Math.sin(theta) * radius,\n z: -Math.cos(theta) * radius, // negative = further from viewer\n};\n\n\n \n;\n```\n\n### Orthographic compare layout\n\nOmit `focalLength` (or set to `0`) — all frames render at equal scale regardless of `world.z`:\n\n```tsx\n\n \n;\n```\n\n## Component Table\n\n| Component | Entry point | Description |\n| ---------------------- | ----------- | ---------------------------------------------------- |\n| `Stage` | `.` | Static device frame |\n| `StageContainer` | `.` | Auto-measures container, provides size via context |\n| `LynxStage` | `./lynx` | Core Lynx bundle renderer (no LUNA globals) |\n| `LunaLynxStage` | `./lynx` | `LynxStage` + LUNA theme prop injection |\n| `MotionStage` | `./motion` | Animated device frame with perspective camera |\n| `MotionStageContainer` | `./motion` | Layout-animated wrapper; provides `MotionValue` size |\n| `MotionPresentation` | `./motion` | Mount/unmount transition orchestrator |\n\n## Hooks\n\n| Export | Entry point | Description |\n| --------------------------- | ----------- | -------------------------------------------------- |\n| `useEventCallback` | `.` | Stable callback that always calls the latest `fn` |\n| `useIsClient` | `.` | SSR-safe client-side mount detection |\n| `useContainerResize` | `.` | Observes container dimensions via `ResizeObserver` |\n| `useMergedRefs` | `.` | Merges multiple refs onto a single element |\n| `useIsomorphicLayoutEffect` | `.` | SSR-safe `useLayoutEffect` |\n| `useLynxStage` | `./lynx` | Core hook for managing Lynx runtime and lifecycle |\n\n## SSR / SSG Notes\n\n`LynxStage` and `LunaLynxStage` are **client-only**. They render `null` on the server and mount only after hydration.\n\n## Bundle & Asset Conventions\n\n- By default, bundle files follow the naming pattern `*.web.bundle`.\n- `bundleRoot` is normalized to a trailing slash by the default resolver.\n- Default resolved URL: `${bundleRoot}${entry}.web.bundle`.\n- Use `resolveBundleSrc` when your host needs a different file naming rule or full URL composition.\n\n## Transform Utilities\n\nThe functions in `src/utils/transform.ts` are zero-dependency pure functions, safe to copy into other projects.\n\n| Function | Description |\n| ---------------------------------------- | ----------------------------------------------------- |\n| `computeScaleRange(input)` | Returns `{ contain, cover }` scale factors |\n| `lerpFitScale(range, t)` | Interpolates between contain and cover |\n| `computeFrameOffset(input)` | Returns `{ offsetX, offsetY }` for CSS transform |\n| `computeDepthScale(focalLength, worldZ)` | Perspective depth scale `f / (f - z)` |\n| `computeScreenTranslation(input)` | Projects world XY + screen pan into final translation |\n\nTo 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.\n","readmeFilename":"README.md"}