@lynx-js/luna-stage 0.0.0-oidc-bootstrap.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (140) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +415 -5
  3. package/dist/components/context/create-context.d.ts +55 -0
  4. package/dist/components/context/create-context.d.ts.map +1 -0
  5. package/dist/components/context/create-context.js +32 -0
  6. package/dist/components/context/create-context.js.map +1 -0
  7. package/dist/components/context/index.d.ts +2 -0
  8. package/dist/components/context/index.d.ts.map +1 -0
  9. package/dist/components/context/index.js +1 -0
  10. package/dist/components/stage/index.d.ts +2 -0
  11. package/dist/components/stage/index.d.ts.map +1 -0
  12. package/dist/components/stage/index.js +1 -0
  13. package/dist/components/stage/stage.d.ts +10 -0
  14. package/dist/components/stage/stage.d.ts.map +1 -0
  15. package/dist/components/stage/stage.js +185 -0
  16. package/dist/components/stage/stage.js.map +1 -0
  17. package/dist/constants/stage.d.ts +4 -0
  18. package/dist/constants/stage.d.ts.map +1 -0
  19. package/dist/constants/stage.js +6 -0
  20. package/dist/constants/stage.js.map +1 -0
  21. package/dist/hooks/index.d.ts +6 -0
  22. package/dist/hooks/index.d.ts.map +1 -0
  23. package/dist/hooks/index.js +5 -0
  24. package/dist/hooks/use-container-resize.d.ts +30 -0
  25. package/dist/hooks/use-container-resize.d.ts.map +1 -0
  26. package/dist/hooks/use-container-resize.js +63 -0
  27. package/dist/hooks/use-container-resize.js.map +1 -0
  28. package/dist/hooks/use-event-callback.d.ts +36 -0
  29. package/dist/hooks/use-event-callback.d.ts.map +1 -0
  30. package/dist/hooks/use-event-callback.js +18 -0
  31. package/dist/hooks/use-event-callback.js.map +1 -0
  32. package/dist/hooks/use-is-client.d.ts +2 -0
  33. package/dist/hooks/use-is-client.d.ts.map +1 -0
  34. package/dist/hooks/use-is-client.js +16 -0
  35. package/dist/hooks/use-is-client.js.map +1 -0
  36. package/dist/hooks/use-isomorphic-layout-effect.d.ts +4 -0
  37. package/dist/hooks/use-isomorphic-layout-effect.d.ts.map +1 -0
  38. package/dist/hooks/use-isomorphic-layout-effect.js +6 -0
  39. package/dist/hooks/use-isomorphic-layout-effect.js.map +1 -0
  40. package/dist/hooks/use-merged-refs.d.ts +5 -0
  41. package/dist/hooks/use-merged-refs.d.ts.map +1 -0
  42. package/dist/hooks/use-merged-refs.js +18 -0
  43. package/dist/hooks/use-merged-refs.js.map +1 -0
  44. package/dist/hooks/use-raf-clock.d.ts +17 -0
  45. package/dist/hooks/use-raf-clock.d.ts.map +1 -0
  46. package/dist/hooks/use-raf-clock.js +22 -0
  47. package/dist/hooks/use-raf-clock.js.map +1 -0
  48. package/dist/index.d.ts +4 -0
  49. package/dist/index.d.ts.map +1 -0
  50. package/dist/index.js +2 -0
  51. package/dist/lynx/index.d.ts +7 -0
  52. package/dist/lynx/index.d.ts.map +1 -0
  53. package/dist/lynx/index.js +3 -0
  54. package/dist/lynx/luna-lynx-stage.d.ts +32 -0
  55. package/dist/lynx/luna-lynx-stage.d.ts.map +1 -0
  56. package/dist/lynx/luna-lynx-stage.js +45 -0
  57. package/dist/lynx/luna-lynx-stage.js.map +1 -0
  58. package/dist/lynx/lynx-stage-constants.d.ts +8 -0
  59. package/dist/lynx/lynx-stage-constants.d.ts.map +1 -0
  60. package/dist/lynx/lynx-stage-constants.js +26 -0
  61. package/dist/lynx/lynx-stage-constants.js.map +1 -0
  62. package/dist/lynx/lynx-stage.d.ts +25 -0
  63. package/dist/lynx/lynx-stage.d.ts.map +1 -0
  64. package/dist/lynx/lynx-stage.js +33 -0
  65. package/dist/lynx/lynx-stage.js.map +1 -0
  66. package/dist/lynx/types.d.ts +77 -0
  67. package/dist/lynx/types.d.ts.map +1 -0
  68. package/dist/lynx/types.js +0 -0
  69. package/dist/lynx/use-lynx-stage.d.ts +5 -0
  70. package/dist/lynx/use-lynx-stage.d.ts.map +1 -0
  71. package/dist/lynx/use-lynx-stage.js +130 -0
  72. package/dist/lynx/use-lynx-stage.js.map +1 -0
  73. package/dist/motion/context/index.d.ts +6 -0
  74. package/dist/motion/context/index.d.ts.map +1 -0
  75. package/dist/motion/context/index.js +3 -0
  76. package/dist/motion/context/use-visual-size.d.ts +8 -0
  77. package/dist/motion/context/use-visual-size.d.ts.map +1 -0
  78. package/dist/motion/context/use-visual-size.js +8 -0
  79. package/dist/motion/context/use-visual-size.js.map +1 -0
  80. package/dist/motion/context/visual-size-context.d.ts +10 -0
  81. package/dist/motion/context/visual-size-context.d.ts.map +1 -0
  82. package/dist/motion/context/visual-size-context.js +5 -0
  83. package/dist/motion/context/visual-size-context.js.map +1 -0
  84. package/dist/motion/context/visual-size-provider.d.ts +9 -0
  85. package/dist/motion/context/visual-size-provider.d.ts.map +1 -0
  86. package/dist/motion/context/visual-size-provider.js +19 -0
  87. package/dist/motion/context/visual-size-provider.js.map +1 -0
  88. package/dist/motion/index.d.ts +5 -0
  89. package/dist/motion/index.d.ts.map +1 -0
  90. package/dist/motion/index.js +2 -0
  91. package/dist/motion/stage/container-motion.d.ts +25 -0
  92. package/dist/motion/stage/container-motion.d.ts.map +1 -0
  93. package/dist/motion/stage/container-motion.js +111 -0
  94. package/dist/motion/stage/container-motion.js.map +1 -0
  95. package/dist/motion/stage/index.d.ts +5 -0
  96. package/dist/motion/stage/index.d.ts.map +1 -0
  97. package/dist/motion/stage/index.js +3 -0
  98. package/dist/motion/stage/presentation-motion.d.ts +17 -0
  99. package/dist/motion/stage/presentation-motion.d.ts.map +1 -0
  100. package/dist/motion/stage/presentation-motion.js +33 -0
  101. package/dist/motion/stage/presentation-motion.js.map +1 -0
  102. package/dist/motion/stage/stage-motion.d.ts +5 -0
  103. package/dist/motion/stage/stage-motion.d.ts.map +1 -0
  104. package/dist/motion/stage/stage-motion.js +184 -0
  105. package/dist/motion/stage/stage-motion.js.map +1 -0
  106. package/dist/motion/stage/transform-utils.d.ts +9 -0
  107. package/dist/motion/stage/transform-utils.d.ts.map +1 -0
  108. package/dist/motion/stage/transform-utils.js +20 -0
  109. package/dist/motion/stage/transform-utils.js.map +1 -0
  110. package/dist/motion/stage/types.d.ts +85 -0
  111. package/dist/motion/stage/types.d.ts.map +1 -0
  112. package/dist/motion/stage/types.js +0 -0
  113. package/dist/motion/stage/use-container-resize-mv.d.ts +13 -0
  114. package/dist/motion/stage/use-container-resize-mv.d.ts.map +1 -0
  115. package/dist/motion/stage/use-container-resize-mv.js +64 -0
  116. package/dist/motion/stage/use-container-resize-mv.js.map +1 -0
  117. package/dist/types/align.d.ts +3 -0
  118. package/dist/types/align.d.ts.map +1 -0
  119. package/dist/types/align.js +0 -0
  120. package/dist/types/index.d.ts +3 -0
  121. package/dist/types/index.d.ts.map +1 -0
  122. package/dist/types/index.js +0 -0
  123. package/dist/types/lynx-view.d.ts +18 -0
  124. package/dist/types/lynx-view.d.ts.map +1 -0
  125. package/dist/types/lynx-view.js +0 -0
  126. package/dist/types/stage-props.d.ts +94 -0
  127. package/dist/types/stage-props.d.ts.map +1 -0
  128. package/dist/types/stage-props.js +0 -0
  129. package/dist/utils/align.d.ts +3 -0
  130. package/dist/utils/align.d.ts.map +1 -0
  131. package/dist/utils/align.js +15 -0
  132. package/dist/utils/align.js.map +1 -0
  133. package/dist/utils/index.d.ts +3 -0
  134. package/dist/utils/index.d.ts.map +1 -0
  135. package/dist/utils/index.js +2 -0
  136. package/dist/utils/transform.d.ts +121 -0
  137. package/dist/utils/transform.d.ts.map +1 -0
  138. package/dist/utils/transform.js +37 -0
  139. package/dist/utils/transform.js.map +1 -0
  140. package/package.json +73 -5
package/LICENSE CHANGED
@@ -198,4 +198,4 @@
198
198
  distributed under the License is distributed on an "AS IS" BASIS,
199
199
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
200
  See the License for the specific language governing permissions and
201
- limitations under the License.
201
+ limitations under the License.
package/README.md CHANGED
@@ -1,9 +1,419 @@
1
- # @lynx-js/luna-stage
1
+ # luna-stage
2
2
 
3
- > Stage system and showcase components for the L.U.N.A project (OIDC bootstrap placeholder)
3
+ > Stage system and showcase components for the L.U.N.A project.
4
+ > Atomic components for rendering Lynx bundles into a device shell / stage in the browser.
4
5
 
5
- This is a placeholder package published only to enable npm Trusted Publishing (OIDC) setup.
6
+ 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 [`@lynx-js/luna-studio`](../luna-studio).
6
7
 
7
- It contains no functional code and should not be installed.
8
+ ## Contents
8
9
 
9
- A proper release will replace this package once OIDC is configured.
10
+ - [Installation](#installation)
11
+ - [Entry Points](#entry-points)
12
+ - [Concepts](#concepts)
13
+ - [Quick Start](#quick-start)
14
+ - [API](#api)
15
+ - [Usage Examples](#usage-examples)
16
+ - [SSR / SSG Notes](#ssr--ssg-notes)
17
+ - [Transform Utilities](#transform-utilities)
18
+
19
+ ## Installation
20
+
21
+ ```sh
22
+ pnpm i @lynx-js/luna-stage
23
+ ```
24
+
25
+ **Peer dependencies** — install in your application:
26
+
27
+ ```sh
28
+ pnpm i react
29
+ ```
30
+
31
+ For Lynx rendering (`LynxStage` / `LunaLynxStage`), install the Lynx Web runtime:
32
+
33
+ ```sh
34
+ pnpm i @lynx-js/web-core
35
+ ```
36
+
37
+ For motion capabilities, install `motion`:
38
+
39
+ ```sh
40
+ pnpm i motion
41
+ ```
42
+
43
+ ## Entry Points
44
+
45
+ | Import path | Requires `motion` | Requires `@lynx-js/web-core` | Use when |
46
+ | -------------------------- | ----------------- | ---------------------------- | --------------------------------------------------------- |
47
+ | `@lynx-js/luna-stage` | No | No | Static device frame + shared hooks |
48
+ | `@lynx-js/luna-stage/lynx` | No | Yes | Lynx bundle rendering (`LynxStage` / `LunaLynxStage`) |
49
+ | `@lynx-js/luna-stage/motion` | Yes | No | Animated transitions + perspective camera (`MotionStage`) |
50
+
51
+ ## Concepts
52
+
53
+ ### Device Frame Model
54
+
55
+ - `baseWidth` / `baseHeight` define the **design baseline** (default `375×812`), not the viewport size.
56
+ - The frame renders at its base dimensions and uses CSS `transform: scale()` to fit into the viewport.
57
+ - Two visual layers: **outline** (decorative border, simulates device thickness) and **frame** (content area with clip-path).
58
+ - `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.
59
+
60
+ ### Fit System
61
+
62
+ - `contain` — scales down to fit fully inside the viewport (no cropping).
63
+ - `cover` — scales up to fully cover the viewport (may crop).
64
+ - `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`.
65
+ - `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).
66
+ - `fitProgress` _(motion only)_ — continuous `0→1` interpolation between `contain` and `cover`, driven by a spring.
67
+
68
+ ### Camera Model _(MotionStage only)_
69
+
70
+ The transform pipeline operates in two independent spaces:
71
+
72
+ **Screen space**
73
+
74
+ - `fit` / `fitProgress` — viewport-driven passive scaling.
75
+ - `zoom` — user-controlled active scaling, applied on top of fit.
76
+ - `panX` / `panY` — screen-space translation in pixels, applied after all scaling.
77
+
78
+ **World space**
79
+
80
+ - `world` — 3D position of the frame `{ x, y, z }`. Follows the CSS/OpenGL convention: `+Z` points toward the viewer.
81
+ - `focalLength` — perspective intensity. When `> 0`, enables perspective projection. When `0` or omitted, orthographic.
82
+ - `world.x/y` are projected into screen space before being composited with `panX/panY`. The spring animates the combined screen-space value.
83
+
84
+ Final scale = `lerpFitScale(contain, cover, fitSpring) × zoom × depthScale`
85
+
86
+ Final translation = `world.xy × depthScale + panXY`
87
+
88
+ ## Quick Start
89
+
90
+ ### Single-frame preview with `LunaLynxStage`
91
+
92
+ ```tsx
93
+ import { Stage, StageContainer } from '@lynx-js/luna-stage';
94
+ import { LunaLynxStage } from '@lynx-js/luna-stage/lynx';
95
+
96
+ export default function Preview() {
97
+ return (
98
+ <StageContainer className='w-full h-screen'>
99
+ <Stage>
100
+ <LunaLynxStage
101
+ entry='my-component'
102
+ bundleRoot='/bundles/'
103
+ lunaTheme='lunaris-dark'
104
+ />
105
+ </Stage>
106
+ </StageContainer>
107
+ );
108
+ }
109
+ ```
110
+
111
+ Default bundle URL convention: `${bundleRoot}${entry}.web.bundle`.
112
+
113
+ Override it with `resolveBundleSrc` when your host uses a different naming rule.
114
+
115
+ `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.
116
+
117
+ `lunaTheme` injects LUNA design token globals into the Lynx runtime.
118
+
119
+ ### Without LUNA theming
120
+
121
+ Use `LynxStage` directly when you don't need LUNA global props forwarded:
122
+
123
+ ```tsx
124
+ import { Stage, StageContainer } from '@lynx-js/luna-stage';
125
+ import { LynxStage } from '@lynx-js/luna-stage/lynx';
126
+
127
+ <StageContainer className='w-full h-screen'>
128
+ <Stage>
129
+ <LynxStage entry='my-component' bundleRoot='/bundles/' />
130
+ </Stage>
131
+ </StageContainer>;
132
+ ```
133
+
134
+ ### Standalone `LynxStage`
135
+
136
+ `LynxStage` can be used independently of the `Stage` system if you just want to render a Lynx view in a DOM container:
137
+
138
+ ```tsx
139
+ import { LynxStage } from '@lynx-js/luna-stage/lynx';
140
+
141
+ export default function StandaloneView() {
142
+ return (
143
+ <div className='w-full h-screen'>
144
+ <LynxStage entry='my-component' bundleRoot='/bundles/' />
145
+ </div>
146
+ );
147
+ }
148
+ ```
149
+
150
+ ## API
151
+
152
+ ### `Stage`
153
+
154
+ Static device frame. Reads viewport size from `StageContainer` context if present, otherwise falls back to `baseWidth/baseHeight`.
155
+
156
+ `Stage` supports two ways to determine its viewport size:
157
+
158
+ **Auto-fit to parent (recommended)** — wrap in `StageContainer` so the viewport auto-measures and the frame fits to it:
159
+
160
+ ```tsx
161
+ <StageContainer className='w-full h-full'>
162
+ <Stage>
163
+ <YourContent />
164
+ </Stage>
165
+ </StageContainer>;
166
+ ```
167
+
168
+ **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:
169
+
170
+ ```tsx
171
+ <Stage width={390} height={844}>
172
+ <YourContent />
173
+ </Stage>;
174
+ ```
175
+
176
+ > **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.
177
+
178
+ #### Props
179
+
180
+ | Prop | Type | Default | Description |
181
+ | ------------ | ------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
182
+ | `baseWidth` | `number` | `375` | Design baseline width in pixels. |
183
+ | `baseHeight` | `number` | `812` | Design baseline height in pixels. |
184
+ | `width` | `number` | — | Explicit viewport size. Drives both rendered `<div>` size and fit/scale. Falls back to `StageContainer` → `baseWidth`. |
185
+ | `height` | `number` | — | Explicit viewport size. Drives both rendered `<div>` size and fit/scale. Falls back to `StageContainer` → `baseHeight`. |
186
+ | `fit` | `'contain' \| 'cover'` | `'contain'` | Fit mode. |
187
+ | `alignX` | `'left' \| 'center' \| 'right'` | `'center'` | Horizontal alignment of frame within viewport. In `cover` mode also determines crop anchor. |
188
+ | `alignY` | `'top' \| 'center' \| 'bottom'` | `'center'` | Vertical alignment of frame within viewport. In `cover` mode also determines crop anchor. |
189
+ | `placeX` | `'left' \| 'center' \| 'right'` | `alignX` | Horizontal placement of the internal anchor within the viewport. Override to decouple placement from alignment. |
190
+ | `placeY` | `'top' \| 'center' \| 'bottom'` | `alignY` | Vertical placement of the internal anchor within the viewport. Override to decouple placement from alignment. |
191
+ | `zoom` | `number` | `1` | Additional zoom factor on top of fit. |
192
+ | `panX` | `number` | `0` | Screen-space translation along X (px). |
193
+ | `panY` | `number` | `0` | Screen-space translation along Y (px). |
194
+ | `className` | `string` | — | Applied to the outline layer. |
195
+ | `style` | `CSSProperties` | — | Applied to the outline layer. |
196
+ | `onClick` | `MouseEventHandler` | — | — |
197
+
198
+ ### `StageContainer`
199
+
200
+ Measures its own DOM size via `ResizeObserver` and provides width/height to child `Stage` components via context.
201
+
202
+ 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.
203
+
204
+ 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.
205
+
206
+ #### Props
207
+
208
+ | Prop | Type | Default | Description |
209
+ | ---------------- | -------- | ------- | ------------------------------ |
210
+ | `fallbackWidth` | `number` | `0` | Used before first measurement. |
211
+ | `fallbackHeight` | `number` | `0` | Used before first measurement. |
212
+
213
+ Inherits all `<div>` HTML attributes (`className`, `style`, etc.).
214
+
215
+ ### `LynxStage`
216
+
217
+ Core component for rendering Lynx bundles into a DOM container.
218
+
219
+ | Prop | Type | Default | Description |
220
+ | --------------------- | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
221
+ | `entry` | `string` | — | Entry name for the Lynx bundle. |
222
+ | `bundleRoot` | `string` | `'/'` | Resource root used with `entry` to locate the bundle. Normalized to always end with `/` before URL resolution. |
223
+ | `resolveBundleSrc` | `function` | — | Optional hook for overriding how the final bundle URL is built. Receives the normalized `bundleRoot` (always ends with `/`). |
224
+ | `globalProps` | `Record<string, unknown>` | — | Global props to inject into the Lynx runtime. |
225
+ | `groupId` | `number` | `7` | Shared Lynx worker group ID. |
226
+ | `onNativeModulesCall` | `function` | — | Callback for native module calls from Lynx runtime. |
227
+ | `onReady` | `function` | — | Callback when the view has rendered successfully. |
228
+ | `onError` | `function` | — | Callback when an error occurs during loading or rendering. |
229
+
230
+ ### `LunaLynxStage`
231
+
232
+ Extends `LynxStage` with LUNA theme properties.
233
+
234
+ | Prop | Type | Default | Description |
235
+ | ------------------ | ------------------------- | -------------- | --------------------------------------------- |
236
+ | `lunaTheme` | `LunaThemeKey` | `'luna-light'` | LUNA theme key (e.g. `'luna-light'`). |
237
+ | `extraGlobalProps` | `Record<string, unknown>` | — | Additional global props. |
238
+ | _(others)_ | | | All `LynxStage` props (except `globalProps`). |
239
+
240
+ ### `MotionStage`
241
+
242
+ Animated device frame. Extends `Stage`'s base props with spring-driven transitions and a perspective camera model.
243
+
244
+ `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.
245
+
246
+ #### Props
247
+
248
+ | Prop | Type | Default | Description |
249
+ | -------------------- | ------------------------------- | ------------------- | -------------------------------------------------------------------------------- |
250
+ | `baseWidth` | `number` | `375` | Design baseline width in pixels. |
251
+ | `baseHeight` | `number` | `812` | Design baseline height in pixels. |
252
+ | `width` | `MotionValue<number>` | — | Override the viewport width (from context). For advanced cases. |
253
+ | `height` | `MotionValue<number>` | — | Override the viewport height (from context). For advanced cases. |
254
+ | `fit` | `'contain' \| 'cover'` | `'contain'` | Fit mode. Ignored when `fitProgress` is set. |
255
+ | `fitProgress` | `number` | — | `0–1` blend between contain and cover, driven by a spring. |
256
+ | `zoom` | `number` | `1` | Additional zoom factor. |
257
+ | `panX` | `number` | `0` | Screen-space translation along X (px). |
258
+ | `panY` | `number` | `0` | Screen-space translation along Y (px). |
259
+ | `world` | `{ x?, y?, z? }` | `{ x:0, y:0, z:0 }` | World-space position. `+Z` toward viewer. |
260
+ | `focalLength` | `number` | — | Perspective focal length (px). Omit for orthographic. |
261
+ | `alignX` | `'left' \| 'center' \| 'right'` | `'center'` | Horizontal alignment of frame within viewport. |
262
+ | `alignY` | `'top' \| 'center' \| 'bottom'` | `'center'` | Vertical alignment of frame within viewport. |
263
+ | `fitTransition` | `SpringOptions` | — | Spring for `fit` / `fitProgress`. |
264
+ | `zoomTransition` | `SpringOptions` | — | Spring for `zoom`. |
265
+ | `panTransition` | `SpringOptions` | — | Spring for combined screen-space translation (`panX/Y` + projected `world.x/y`). |
266
+ | `maskColor` | `string` | `'transparent'` | Overlay mask color. |
267
+ | `maskOpacity` | `number` | `0` | Overlay mask opacity (animated). |
268
+ | `contentInteractive` | `boolean` | `false` | Whether the frame's children receive pointer events. |
269
+ | `className` | `string` | — | Applied to the outline layer. |
270
+ | `style` | `MotionStyle` | — | Applied to the outline layer. |
271
+
272
+ ### `MotionStageContainer`
273
+
274
+ 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.
275
+
276
+ Must be used as a child of `<AnimatePresence>` for mount/unmount animations to work.
277
+
278
+ #### Props
279
+
280
+ | Prop | Type | Default | Description |
281
+ | --------------------------- | -------------------- | ------- | ----------------------------------------------------------------------- |
282
+ | `layoutId` | `string` | — | Unique ID for layout animation matching across mount/unmount. Required. |
283
+ | `onLayoutMeasure` | `(box: Box) => void` | — | Forwarded from `motion`. Called when layout box is measured. |
284
+ | `onLayoutAnimationStart` | `() => void` | — | Forwarded from `motion`. Called when layout animation starts. |
285
+ | `onLayoutAnimationComplete` | `() => void` | — | Forwarded from `motion`. Called when layout animation completes. |
286
+
287
+ Inherits all `motion.div` props (except `transformTemplate`, which is used internally).
288
+
289
+ ### `MotionPresentation`
290
+
291
+ A zero-size flex-centered anchor that wraps `AnimatePresence propagate` for descendant mount/unmount animations.
292
+
293
+ **Use when:** items are dynamically added/removed and need mount/unmount animations.
294
+
295
+ **Skip when:** components are always mounted, or you only need state transition animations.
296
+
297
+ Inherits all `motion.div` props (`variants`, `initial`, `animate`, `exit`, `transition`, etc.).
298
+
299
+ ## Usage Examples
300
+
301
+ ### Motion: no mount/unmount
302
+
303
+ ```tsx
304
+ import { MotionStage, MotionStageContainer } from '@lynx-js/luna-stage/motion';
305
+
306
+ <MotionStageContainer className='w-full h-full' layoutId='stage-1'>
307
+ <MotionStage fitProgress={0} zoom={1.2}>
308
+ <YourContent />
309
+ </MotionStage>
310
+ </MotionStageContainer>;
311
+ ```
312
+
313
+ ### Motion: with mount/unmount animations
314
+
315
+ ```tsx
316
+ import { AnimatePresence } from 'motion/react';
317
+ import {
318
+ MotionStage,
319
+ MotionStageContainer,
320
+ MotionPresentation,
321
+ } from '@lynx-js/luna-stage/motion';
322
+
323
+ const variants = {
324
+ initial: { opacity: 0, x: -300 },
325
+ animate: { opacity: 1, x: 0 },
326
+ exit: { opacity: 0, x: 300 },
327
+ };
328
+
329
+ <AnimatePresence mode='popLayout'>
330
+ {items.map(item => (
331
+ <MotionStageContainer key={item.id} layoutId={item.id}>
332
+ <MotionPresentation
333
+ variants={variants}
334
+ initial='initial'
335
+ animate='animate'
336
+ exit='exit'
337
+ >
338
+ <MotionStage world={item.world} focalLength={500}>
339
+ <YourContent />
340
+ </MotionStage>
341
+ </MotionPresentation>
342
+ </MotionStageContainer>
343
+ ))}
344
+ </AnimatePresence>;
345
+ ```
346
+
347
+ ### Perspective carousel
348
+
349
+ Arrange frames along a circular arc. `+Z` is toward the viewer, so objects at `z < 0` appear further away:
350
+
351
+ ```tsx
352
+ const theta = (index - mid) * (Math.PI / 9); // 20° apart
353
+ const world = {
354
+ x: Math.sin(theta) * radius,
355
+ z: -Math.cos(theta) * radius, // negative = further from viewer
356
+ };
357
+
358
+ <MotionStage world={world} focalLength={500}>
359
+ <YourContent />
360
+ </MotionStage>;
361
+ ```
362
+
363
+ ### Orthographic compare layout
364
+
365
+ Omit `focalLength` (or set to `0`) — all frames render at equal scale regardless of `world.z`:
366
+
367
+ ```tsx
368
+ <MotionStage world={{ x: offset, y: 0, z: 0 }}>
369
+ <YourContent />
370
+ </MotionStage>;
371
+ ```
372
+
373
+ ## Component Table
374
+
375
+ | Component | Entry point | Description |
376
+ | ---------------------- | ----------- | ---------------------------------------------------- |
377
+ | `Stage` | `.` | Static device frame |
378
+ | `StageContainer` | `.` | Auto-measures container, provides size via context |
379
+ | `LynxStage` | `./lynx` | Core Lynx bundle renderer (no LUNA globals) |
380
+ | `LunaLynxStage` | `./lynx` | `LynxStage` + LUNA theme prop injection |
381
+ | `MotionStage` | `./motion` | Animated device frame with perspective camera |
382
+ | `MotionStageContainer` | `./motion` | Layout-animated wrapper; provides `MotionValue` size |
383
+ | `MotionPresentation` | `./motion` | Mount/unmount transition orchestrator |
384
+
385
+ ## Hooks
386
+
387
+ | Export | Entry point | Description |
388
+ | --------------------------- | ----------- | -------------------------------------------------- |
389
+ | `useEventCallback` | `.` | Stable callback that always calls the latest `fn` |
390
+ | `useIsClient` | `.` | SSR-safe client-side mount detection |
391
+ | `useContainerResize` | `.` | Observes container dimensions via `ResizeObserver` |
392
+ | `useMergedRefs` | `.` | Merges multiple refs onto a single element |
393
+ | `useIsomorphicLayoutEffect` | `.` | SSR-safe `useLayoutEffect` |
394
+ | `useLynxStage` | `./lynx` | Core hook for managing Lynx runtime and lifecycle |
395
+
396
+ ## SSR / SSG Notes
397
+
398
+ `LynxStage` and `LunaLynxStage` are **client-only**. They render `null` on the server and mount only after hydration.
399
+
400
+ ## Bundle & Asset Conventions
401
+
402
+ - By default, bundle files follow the naming pattern `*.web.bundle`.
403
+ - `bundleRoot` is normalized to a trailing slash by the default resolver.
404
+ - Default resolved URL: `${bundleRoot}${entry}.web.bundle`.
405
+ - Use `resolveBundleSrc` when your host needs a different file naming rule or full URL composition.
406
+
407
+ ## Transform Utilities
408
+
409
+ The functions in `src/utils/transform.ts` are zero-dependency pure functions, safe to copy into other projects.
410
+
411
+ | Function | Description |
412
+ | ---------------------------------------- | ----------------------------------------------------- |
413
+ | `computeScaleRange(input)` | Returns `{ contain, cover }` scale factors |
414
+ | `lerpFitScale(range, t)` | Interpolates between contain and cover |
415
+ | `computeFrameOffset(input)` | Returns `{ offsetX, offsetY }` for CSS transform |
416
+ | `computeDepthScale(focalLength, worldZ)` | Perspective depth scale `f / (f - z)` |
417
+ | `computeScreenTranslation(input)` | Projects world XY + screen pan into final translation |
418
+
419
+ 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.
@@ -0,0 +1,55 @@
1
+ import type { ReactNode } from 'react';
2
+ /**
3
+ * Creates a Context with an auto-generated Provider and Hook.
4
+ * @param contextName - The Context name, used in error messages.
5
+ * @param defaultValue - The default value (optional).
6
+ * @returns A tuple containing [Provider, useContext].
7
+ *
8
+ * @example
9
+ * ```tsx
10
+ * // Define the type.
11
+ * interface UserContextType {
12
+ * user: { id: string; name: string } | null;
13
+ * setUser: (user: { id: string; name: string } | null) => void;
14
+ * }
15
+ *
16
+ * // Create the Context.
17
+ * const [UserProvider, useUser] = createContextWithProvider<UserContextType>('User');
18
+ *
19
+ * // Use the Context in an application.
20
+ * function App() {
21
+ * const [user, setUser] = useState(null);
22
+ *
23
+ * return (
24
+ * <UserProvider user={user} setUser={setUser}>
25
+ * <UserProfile />
26
+ * </UserProvider>
27
+ * );
28
+ * }
29
+ *
30
+ * function UserProfile() {
31
+ * const { user, setUser } = useUser();
32
+ * // ...
33
+ * }
34
+ * ```
35
+ */
36
+ declare function createContextWithProvider<T extends object | null>(contextName: string, defaultValue: T, options?: {
37
+ throwIfMissing?: true;
38
+ }): readonly [(p: T & {
39
+ children: ReactNode;
40
+ }) => JSX.Element, () => T];
41
+ declare function createContextWithProvider<T extends object | null>(contextName: string, defaultValue: undefined, options: {
42
+ throwIfMissing: false;
43
+ }): readonly [
44
+ (p: T & {
45
+ children: ReactNode;
46
+ }) => JSX.Element,
47
+ () => T | undefined
48
+ ];
49
+ declare function createContextWithProvider<T extends object | null>(contextName: string, defaultValue?: undefined, options?: {
50
+ throwIfMissing?: true;
51
+ }): readonly [(p: T & {
52
+ children: ReactNode;
53
+ }) => JSX.Element, () => T];
54
+ export { createContextWithProvider };
55
+ //# sourceMappingURL=create-context.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"create-context.d.ts","sourceRoot":"","sources":["../../../src/components/context/create-context.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,iBAAS,yBAAyB,CAAC,CAAC,SAAS,MAAM,GAAG,IAAI,EACxD,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,CAAC,EACf,OAAO,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,IAAI,CAAA;CAAE,GAClC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,KAAK,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;AAEtE,iBAAS,yBAAyB,CAAC,CAAC,SAAS,MAAM,GAAG,IAAI,EACxD,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,SAAS,EACvB,OAAO,EAAE;IAAE,cAAc,EAAE,KAAK,CAAA;CAAE,GACjC,SAAS;IACV,CAAC,CAAC,EAAE,CAAC,GAAG;QAAE,QAAQ,EAAE,SAAS,CAAA;KAAE,KAAK,GAAG,CAAC,OAAO;IAC/C,MAAM,CAAC,GAAG,SAAS;CACpB,CAAA;AAED,iBAAS,yBAAyB,CAAC,CAAC,SAAS,MAAM,GAAG,IAAI,EACxD,WAAW,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,SAAS,EACxB,OAAO,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,IAAI,CAAA;CAAE,GAClC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,KAAK,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;AAsDtE,OAAO,EAAE,yBAAyB,EAAE,CAAA"}
@@ -0,0 +1,32 @@
1
+ import { jsx } from "react/jsx-runtime";
2
+ import { createContext, useContext } from "react";
3
+ function createContextWithProvider(contextName, defaultValue, options) {
4
+ const { throwIfMissing = true } = options ?? {};
5
+ const Context = /*#__PURE__*/ createContext(defaultValue);
6
+ Context.displayName = `${contextName}Context`;
7
+ const Provider = (props)=>{
8
+ const { children, ...context } = props;
9
+ return /*#__PURE__*/ jsx(Context.Provider, {
10
+ value: context,
11
+ children: children
12
+ });
13
+ };
14
+ Provider.displayName = `${contextName}Provider`;
15
+ function useContextValue() {
16
+ const context = useContext(Context);
17
+ if (void 0 !== context) return context;
18
+ if (void 0 !== defaultValue) return defaultValue;
19
+ if (throwIfMissing) throw new Error(`use${contextName} must be used within a ${contextName}Provider.`);
20
+ }
21
+ Object.defineProperty(useContextValue, 'name', {
22
+ value: `use${contextName}`,
23
+ configurable: true
24
+ });
25
+ return [
26
+ Provider,
27
+ useContextValue
28
+ ];
29
+ }
30
+ export { createContextWithProvider };
31
+
32
+ //# sourceMappingURL=create-context.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"components/context/create-context.js","sources":["../../../src/components/context/create-context.tsx"],"sourcesContent":["// Copyright 2026 The Lynx Authors. All rights reserved.\n// Licensed under the Apache License Version 2.0 that can be found in the\n// LICENSE file in the root directory of this source tree.\n\nimport { createContext, useContext } from 'react'\nimport type { ReactNode } from 'react'\n\n/**\n * Creates a Context with an auto-generated Provider and Hook.\n * @param contextName - The Context name, used in error messages.\n * @param defaultValue - The default value (optional).\n * @returns A tuple containing [Provider, useContext].\n *\n * @example\n * ```tsx\n * // Define the type.\n * interface UserContextType {\n * user: { id: string; name: string } | null;\n * setUser: (user: { id: string; name: string } | null) => void;\n * }\n *\n * // Create the Context.\n * const [UserProvider, useUser] = createContextWithProvider<UserContextType>('User');\n *\n * // Use the Context in an application.\n * function App() {\n * const [user, setUser] = useState(null);\n *\n * return (\n * <UserProvider user={user} setUser={setUser}>\n * <UserProfile />\n * </UserProvider>\n * );\n * }\n *\n * function UserProfile() {\n * const { user, setUser } = useUser();\n * // ...\n * }\n * ```\n */\nfunction createContextWithProvider<T extends object | null>(\n contextName: string,\n defaultValue: T,\n options?: { throwIfMissing?: true },\n): readonly [(p: T & { children: ReactNode }) => JSX.Element, () => T]\n\nfunction createContextWithProvider<T extends object | null>(\n contextName: string,\n defaultValue: undefined,\n options: { throwIfMissing: false },\n): readonly [\n (p: T & { children: ReactNode }) => JSX.Element,\n () => T | undefined,\n]\n\nfunction createContextWithProvider<T extends object | null>(\n contextName: string,\n defaultValue?: undefined,\n options?: { throwIfMissing?: true },\n): readonly [(p: T & { children: ReactNode }) => JSX.Element, () => T]\n\nfunction createContextWithProvider<\n T extends object | null,\n>(\n contextName: string,\n defaultValue?: T,\n options?: { throwIfMissing?: boolean },\n) {\n const { throwIfMissing = true } = options ?? {}\n\n const Context = createContext<T | undefined>(defaultValue)\n\n // Generates a clearer displayName for the Provider and Hook.\n Context.displayName = `${contextName}Context`\n\n const Provider = (\n props: T & { children: ReactNode },\n ) => {\n const { children, ...context } = props\n\n return (\n <Context.Provider value={context as T}>\n {children}\n </Context.Provider>\n )\n }\n\n // Sets the displayName of the Provider for easier debugging.\n Provider.displayName = `${contextName}Provider`\n\n function useContextValue(): T {\n const context = useContext(Context)\n if (context !== undefined) return context\n if (defaultValue !== undefined) return defaultValue\n\n if (throwIfMissing) {\n throw new Error(\n `use${contextName} must be used within a ${contextName}Provider.`,\n )\n }\n\n return undefined as unknown as T\n }\n\n // Sets the name of the Hook function.\n Object.defineProperty(useContextValue, 'name', {\n value: `use${contextName}`,\n configurable: true,\n })\n\n return [Provider, useContextValue] as const\n}\n\nexport { createContextWithProvider }\n"],"names":["createContextWithProvider","contextName","defaultValue","options","throwIfMissing","Context","createContext","Provider","props","children","context","useContextValue","useContext","undefined","Error","Object"],"mappings":";;AA8DA,SAASA,0BAGPC,WAAmB,EACnBC,YAAgB,EAChBC,OAAsC;IAEtC,MAAM,EAAEC,iBAAiB,IAAI,EAAE,GAAGD,WAAW,CAAC;IAE9C,MAAME,UAAU,WAAVA,GAAUC,cAA6BJ;IAG7CG,QAAQ,WAAW,GAAG,GAAGJ,YAAY,OAAO,CAAC;IAE7C,MAAMM,WAAW,CACfC;QAEA,MAAM,EAAEC,QAAQ,EAAE,GAAGC,SAAS,GAAGF;QAEjC,OAAO,WAAP,GACE,IAACH,QAAQ,QAAQ;YAAC,OAAOK;sBACtBD;;IAGP;IAGAF,SAAS,WAAW,GAAG,GAAGN,YAAY,QAAQ,CAAC;IAE/C,SAASU;QACP,MAAMD,UAAUE,WAAWP;QAC3B,IAAIK,AAAYG,WAAZH,SAAuB,OAAOA;QAClC,IAAIR,AAAiBW,WAAjBX,cAA4B,OAAOA;QAEvC,IAAIE,gBACF,MAAM,IAAIU,MACR,CAAC,GAAG,EAAEb,YAAY,uBAAuB,EAAEA,YAAY,SAAS,CAAC;IAKvE;IAGAc,OAAO,cAAc,CAACJ,iBAAiB,QAAQ;QAC7C,OAAO,CAAC,GAAG,EAAEV,aAAa;QAC1B,cAAc;IAChB;IAEA,OAAO;QAACM;QAAUI;KAAgB;AACpC"}
@@ -0,0 +1,2 @@
1
+ export { createContextWithProvider } from './create-context';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/context/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAA"}
@@ -0,0 +1 @@
1
+ export { createContextWithProvider } from "./create-context.js";
@@ -0,0 +1,2 @@
1
+ export { Stage, StageContainer } from './stage';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/stage/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA"}
@@ -0,0 +1 @@
1
+ export { Stage, StageContainer } from "./stage.js";
@@ -0,0 +1,10 @@
1
+ import type { DetailedHTMLProps, ForwardRefExoticComponent, HTMLAttributes, RefAttributes } from 'react';
2
+ import type { JSX } from 'react/jsx-runtime';
3
+ import type { StageProps } from '../../types';
4
+ declare function Stage({ className, style, width: widthProp, height: heightProp, fit, alignX, alignY, placeX, placeY, children, baseWidth, baseHeight, zoom, panX, panY, }: StageProps): JSX.Element;
5
+ declare const StageContainer: ForwardRefExoticComponent<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, 'ref'> & {
6
+ fallbackWidth?: number;
7
+ fallbackHeight?: number;
8
+ } & RefAttributes<HTMLDivElement>>;
9
+ export { Stage, StageContainer };
10
+ //# sourceMappingURL=stage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../../../src/components/stage/stage.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,iBAAiB,EACjB,yBAAyB,EAEzB,cAAc,EACd,aAAa,EACd,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAA;AAS5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAwE7C,iBAAS,KAAK,CAAC,EACb,SAAS,EACT,KAAK,EACL,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,UAAU,EAClB,GAAe,EACf,MAAiB,EACjB,MAAiB,EACjB,MAAM,EACN,MAAM,EACN,QAAQ,EACR,SAAe,EACf,UAAgB,EAChB,IAAQ,EACR,IAAQ,EACR,IAAQ,GACT,EAAE,UAAU,GAAG,GAAG,CAAC,OAAO,CA4H1B;AAmCD,QAAA,MAAM,cAAc,EAAE,yBAAyB,CAC3C,IAAI,CACJ,iBAAiB,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC,EACjE,KAAK,CACN,GACC;IACA,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,GACC,aAAa,CAAC,cAAc,CAAC,CACC,CAAA;AAElC,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,CAAA"}