@senseihq/emaki-react 0.0.0-stage → 0.1.0

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SenecaGlobal
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,34 @@
1
- # Temporary Holding Version
1
+ # @senseihq/emaki-react
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ React components and hooks for motion stories, over `@senseihq/emaki`. React 18+; client components (in Next.js,
4
+ import them from a `'use client'` file).
5
+
6
+ ```sh
7
+ npm i @senseihq/emaki @senseihq/emaki-react
8
+ ```
9
+
10
+ ```tsx
11
+ import { MotionScene, MotionShow, ScenePlayer, ShowPage, ScenePlayerState, useScenePlayer, useShowState } from '@senseihq/emaki-react';
12
+
13
+ <MotionScene film="phishing-101" scene="signs" locale="es" /> // article figure, loops while visible
14
+ <div style={{ aspectRatio: '16/10' }}><MotionShow film="phishing-101" locale="es" onReady={setShow} /></div>
15
+ <ScenePlayer player={player} controls /> // a scene you drive
16
+ <ShowPage film={film} capture layout="portrait" locale="es" /> // the /show/[film] capture page
17
+ ```
18
+
19
+ Call `setupMotion({ source, site, logos })` once on the client first (`emaki init` writes the source file).
20
+
21
+ | Export | What |
22
+ |---|---|
23
+ | `MotionScene` | `film`, `scene`, `layout` (`figure`), `locale`, `mode` (`auto`), `autoplay` |
24
+ | `MotionShow` | `film`, `locale`, `layout`, `mode` (`auto`), `controls`, `slide`, `loop`, `onReady(show)` |
25
+ | `ScenePlayer` | `player`, `locale`, `mode` (`auto`), `controls` |
26
+ | `ShowPage` | `film`, `layout`, `locale`, `mode` (capture: `light`), `capture` |
27
+ | `useScenePlayer(player)` | re-renders on every change of a `ScenePlayerState` (useSyncExternalStore) |
28
+ | `usePlayerFor(ref)` | a player you own, pointed at `{ film, scene, layout }` |
29
+ | `useShowState(show)` | `{ index, playing, sound, layout }` of a player controller |
30
+
31
+ `mode` is `light`, `dark` or `auto`. Auto follows the page's `data-mode` (as rokkit's `themable` sets it), else the
32
+ OS, and the scenes redraw when it changes. A film draws dark only if it has a dark look (see @senseihq/emaki).
33
+
34
+ MIT © SenecaGlobal
@@ -0,0 +1,49 @@
1
+ import { type CSSProperties } from 'react';
2
+ import { type Layout, type Mode, type ScenePlayerState } from '@senseihq/emaki';
3
+ import { type Show } from './hooks.js';
4
+ export interface MotionSceneProps {
5
+ film: string;
6
+ scene: string;
7
+ layout?: Layout;
8
+ locale?: string;
9
+ mode?: Mode;
10
+ autoplay?: boolean;
11
+ className?: string;
12
+ style?: CSSProperties;
13
+ }
14
+ /** An article figure: one scene, looping while it is on screen. */
15
+ export declare function MotionScene({ film, scene, layout, locale, mode, autoplay, className, style }: MotionSceneProps): import("react").JSX.Element;
16
+ export interface ScenePlayerProps {
17
+ player: ScenePlayerState;
18
+ locale?: string;
19
+ mode?: Mode;
20
+ controls?: boolean;
21
+ className?: string;
22
+ }
23
+ /** A scene driven by a ScenePlayerState you own (editors, previews, step-throughs). */
24
+ export declare function ScenePlayer({ player, locale, mode, controls, className }: ScenePlayerProps): import("react").JSX.Element;
25
+ export interface MotionShowProps {
26
+ film: string;
27
+ locale?: string;
28
+ layout?: Layout;
29
+ mode?: Mode;
30
+ controls?: boolean;
31
+ slide?: number;
32
+ loop?: boolean;
33
+ /** The controller once ready (next/prev/play/pause/setSound/setLayout/seek/on), for custom chrome. */
34
+ onReady?: (show: Show) => void;
35
+ className?: string;
36
+ style?: CSSProperties;
37
+ }
38
+ /** The story player: a film's scenes as slides, fitted to its box. Keys: ←/→, Space, M (sound), O (orientation). */
39
+ export declare function MotionShow({ film, locale, layout, mode, controls, slide, loop, onReady, className, style }: MotionShowProps): import("react").JSX.Element;
40
+ /** mode: capture renders light unless asked; the interactive player follows the page (auto). */
41
+ export interface ShowPageProps {
42
+ film: string;
43
+ layout?: Layout;
44
+ locale?: string;
45
+ mode?: Mode;
46
+ capture?: boolean;
47
+ }
48
+ /** The /show/<film> page the video pipeline drives: with `capture`, the stage at 1:1, no chrome, window.__show. */
49
+ export declare function ShowPage({ film, layout, locale, mode, capture }: ShowPageProps): import("react").JSX.Element;
@@ -0,0 +1,88 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ // React components over @senseihq/emaki. All are client components (they need the DOM); in Next.js import them
3
+ // from a file marked 'use client'. Call setupMotion({ source, site, logos }) once on the client first.
4
+ import { useEffect, useRef, useState } from 'react';
5
+ import { attachScene, createShow, installCapture } from '@senseihq/emaki';
6
+ import { usePlayerFor, useScenePlayer, useShowState, useSize, useWidth } from './hooks.js';
7
+ /** Mounts a player's scene into a div and keeps it fitted (shared by MotionScene and ScenePlayer). */
8
+ function useAttached(player, locale, mode, autoplay) {
9
+ const [ref, width] = useWidth();
10
+ const host = useRef(null);
11
+ const view = useRef(null);
12
+ useEffect(() => {
13
+ view.current = attachScene(host.current, player, { locale, mode, autoplay });
14
+ return () => { view.current?.destroy(); view.current = null; };
15
+ }, [player]); // eslint-disable-line react-hooks/exhaustive-deps
16
+ useEffect(() => { view.current?.setLocale(locale); }, [locale]);
17
+ useEffect(() => { view.current?.setMode(mode); }, [mode]);
18
+ useEffect(() => { if (width)
19
+ view.current?.fit(width); }, [width]);
20
+ return { ref, host };
21
+ }
22
+ /** An article figure: one scene, looping while it is on screen. */
23
+ export function MotionScene({ film, scene, layout = 'figure', locale = 'en', mode = 'auto', autoplay = true, className, style }) {
24
+ const player = usePlayerFor({ film, scene, layout });
25
+ const { ref, host } = useAttached(player, locale, mode, autoplay);
26
+ return _jsx("div", { ref: ref, className: className, style: { width: '100%', ...style }, children: _jsx("div", { ref: host }) });
27
+ }
28
+ /** A scene driven by a ScenePlayerState you own (editors, previews, step-throughs). */
29
+ export function ScenePlayer({ player, locale = 'en', mode = 'auto', controls = false, className }) {
30
+ const p = useScenePlayer(player);
31
+ const { ref, host } = useAttached(player, locale, mode, false);
32
+ const msg = { position: 'absolute', inset: 0, display: 'grid', placeItems: 'center', margin: 0, font: '14px system-ui' };
33
+ return (_jsxs("div", { ref: ref, className: className, style: { position: 'relative', width: '100%' }, children: [_jsx("div", { ref: host }), p.status === 'error' && _jsx("p", { role: "alert", style: { ...msg, color: '#b42318' }, children: p.error }), p.status === 'idle' && _jsx("p", { style: { ...msg, opacity: 0.7 }, children: "Loading the scene\u2026" }), controls && p.status === 'ready' && (_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 12, marginTop: 10, font: '12px ui-monospace, monospace' }, children: [_jsx("button", { onClick: () => p.toggle(), "aria-label": p.playing ? 'Pause' : 'Play', children: p.playing ? '❚❚' : '▶' }), _jsx("input", { type: "range", "aria-label": "Seek", min: 0, max: p.dur, step: 0.05, value: p.t, onChange: (e) => p.seek(Number(e.target.value)), style: { flex: 1 } }), _jsxs("span", { children: [p.t.toFixed(1), " / ", p.dur.toFixed(1)] })] }))] }));
34
+ }
35
+ /** The story player: a film's scenes as slides, fitted to its box. Keys: ←/→, Space, M (sound), O (orientation). */
36
+ export function MotionShow({ film, locale = 'en', layout = 'landscape', mode = 'auto', controls = true, slide = 1, loop = false, onReady, className, style }) {
37
+ const stage = useRef(null);
38
+ const [fitRef, size] = useSize();
39
+ const [show, setShow] = useState(null);
40
+ const st = useShowState(show);
41
+ useEffect(() => {
42
+ let alive = true, made = null;
43
+ createShow(stage.current, film, { locale, layout, mode, slide, loop }).then((s) => {
44
+ if (!alive)
45
+ return s.destroy();
46
+ made = s;
47
+ setShow(s);
48
+ onReady?.(s);
49
+ });
50
+ return () => { alive = false; made?.destroy(); setShow(null); };
51
+ }, [film, locale, mode]); // eslint-disable-line react-hooks/exhaustive-deps
52
+ useEffect(() => { if (show && show.state.layout !== layout)
53
+ show.setLayout(layout); }, [show, layout]);
54
+ useEffect(() => { show?.fit(size.w, size.h); }, [show, size, st?.layout]);
55
+ const onKeyDown = (e) => {
56
+ if (!show)
57
+ return;
58
+ const k = e.key.toLowerCase();
59
+ if (k === 'arrowright')
60
+ show.next();
61
+ else if (k === 'arrowleft')
62
+ show.prev();
63
+ else if (k === ' ') {
64
+ show.toggle();
65
+ e.preventDefault();
66
+ }
67
+ else if (k === 'm')
68
+ show.setSound(!show.state.sound);
69
+ else if (k === 'o')
70
+ show.setLayout(show.state.layout === 'landscape' ? 'portrait' : 'landscape');
71
+ };
72
+ const btn = { minWidth: 34, height: 34, borderRadius: 17, border: '1px solid currentColor', background: 'none', color: 'inherit', cursor: 'pointer', padding: '0 10px' };
73
+ return (_jsxs("div", { tabIndex: 0, role: "application", "aria-label": "Story player", onKeyDown: onKeyDown, className: className, style: { position: 'relative', width: '100%', height: '100%', display: 'flex', flexDirection: 'column', outline: 'none', ...style }, children: [_jsx("div", { ref: fitRef, style: { position: 'relative', flex: 1, minHeight: 0, display: 'grid', placeItems: 'center', overflow: 'hidden' }, children: _jsx("div", { ref: stage, style: { position: 'relative' } }) }), controls && show && st && (_jsxs("div", { style: { display: 'flex', gap: 8, alignItems: 'center', justifyContent: 'center', padding: 8, font: '13px system-ui' }, children: [_jsx("button", { style: btn, onClick: () => show.prev(), "aria-label": "Previous scene", children: "\u2039" }), _jsx("button", { style: btn, onClick: () => show.toggle(), "aria-label": st.playing ? 'Pause' : 'Play', children: st.playing ? '❚❚' : '▶' }), _jsx("button", { style: btn, onClick: () => show.next(), "aria-label": "Next scene", children: "\u203A" }), _jsxs("span", { style: { opacity: 0.7 }, children: [st.index + 1, " / ", show.timeline.scenes.length] }), _jsx("button", { style: btn, onClick: () => show.setSound(!st.sound), "aria-pressed": st.sound, children: st.sound ? 'Sound on' : 'Sound off' })] }))] }));
74
+ }
75
+ /** The /show/<film> page the video pipeline drives: with `capture`, the stage at 1:1, no chrome, window.__show. */
76
+ export function ShowPage({ film, layout = 'landscape', locale = 'en', mode, capture = false }) {
77
+ const host = useRef(null);
78
+ useEffect(() => {
79
+ if (!capture)
80
+ return;
81
+ let s = null;
82
+ installCapture(host.current, film, layout, locale, mode ?? 'light').then((x) => { s = x; });
83
+ return () => s?.destroy();
84
+ }, [capture, film, layout, locale, mode]);
85
+ if (capture)
86
+ return _jsx("div", { ref: host });
87
+ return _jsx("div", { style: { position: 'fixed', inset: 0 }, children: _jsx(MotionShow, { film: film, layout: layout, locale: locale, mode: mode ?? 'auto' }) });
88
+ }
@@ -0,0 +1,21 @@
1
+ import { ScenePlayerState, type createShow, type Layout, type SceneRef } from '@senseihq/emaki';
2
+ /** Re-renders whenever the player changes; returns it for reads (p.t, p.playing, p.status) and calls (p.seek(2)). */
3
+ export declare function useScenePlayer(player: ScenePlayerState): ScenePlayerState;
4
+ /** A player you own, created once and pointed at `ref` (reloads when film, scene or layout change). */
5
+ export declare function usePlayerFor(ref: SceneRef | null): ScenePlayerState;
6
+ export type Show = Awaited<ReturnType<typeof createShow>>;
7
+ export interface ShowState {
8
+ index: number;
9
+ local: number;
10
+ playing: boolean;
11
+ sound: boolean;
12
+ layout: Layout;
13
+ }
14
+ /** State of a story player controller (from <MotionShow onReady>): re-renders on scene, play, sound, layout changes. */
15
+ export declare function useShowState(show: Show | null): ShowState | null;
16
+ /** Width of an element, tracked with a ResizeObserver. */
17
+ export declare function useWidth<T extends HTMLElement>(): readonly [import("react").RefObject<T | null>, number];
18
+ export declare function useSize<T extends HTMLElement>(): readonly [import("react").RefObject<T | null>, {
19
+ w: number;
20
+ h: number;
21
+ }];
package/dist/hooks.js ADDED
@@ -0,0 +1,55 @@
1
+ // React state over the core: the core notifies, useSyncExternalStore re-renders. Nothing here touches the DOM.
2
+ import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
3
+ import { ScenePlayerState } from '@senseihq/emaki';
4
+ /** Re-renders whenever the player changes; returns it for reads (p.t, p.playing, p.status) and calls (p.seek(2)). */
5
+ export function useScenePlayer(player) {
6
+ useSyncExternalStore((cb) => player.subscribe(cb), () => player.version, () => player.version);
7
+ return player;
8
+ }
9
+ /** A player you own, created once and pointed at `ref` (reloads when film, scene or layout change). */
10
+ export function usePlayerFor(ref) {
11
+ const player = useMemo(() => new ScenePlayerState(), []);
12
+ const key = ref ? `${ref.film}:${ref.scene}:${ref.layout}:${ref.src ?? ''}` : '';
13
+ useEffect(() => { if (ref)
14
+ player.load(ref); }, [key]); // eslint-disable-line react-hooks/exhaustive-deps
15
+ return useScenePlayer(player);
16
+ }
17
+ /** State of a story player controller (from <MotionShow onReady>): re-renders on scene, play, sound, layout changes. */
18
+ export function useShowState(show) {
19
+ const [st, setSt] = useState(show ? show.state : null);
20
+ const last = useRef(show);
21
+ useEffect(() => {
22
+ last.current = show;
23
+ if (!show)
24
+ return setSt(null);
25
+ setSt(show.state);
26
+ const off = show.on((s) => setSt({ ...s }));
27
+ return () => { off(); };
28
+ }, [show]);
29
+ return st;
30
+ }
31
+ /** Width of an element, tracked with a ResizeObserver. */
32
+ export function useWidth() {
33
+ const ref = useRef(null);
34
+ const [w, setW] = useState(0);
35
+ useEffect(() => {
36
+ if (!ref.current)
37
+ return;
38
+ const ro = new ResizeObserver(([e]) => setW(e.contentRect.width));
39
+ ro.observe(ref.current);
40
+ return () => ro.disconnect();
41
+ }, []);
42
+ return [ref, w];
43
+ }
44
+ export function useSize() {
45
+ const ref = useRef(null);
46
+ const [s, setS] = useState({ w: 0, h: 0 });
47
+ useEffect(() => {
48
+ if (!ref.current)
49
+ return;
50
+ const ro = new ResizeObserver(([e]) => setS({ w: e.contentRect.width, h: e.contentRect.height }));
51
+ ro.observe(ref.current);
52
+ return () => ro.disconnect();
53
+ }, []);
54
+ return [ref, s];
55
+ }
@@ -0,0 +1,3 @@
1
+ export { MotionScene, MotionShow, ScenePlayer, ShowPage, type MotionSceneProps, type MotionShowProps, type ScenePlayerProps, type ShowPageProps } from './components.js';
2
+ export { useScenePlayer, usePlayerFor, useShowState, type Show, type ShowState } from './hooks.js';
3
+ export { setupMotion, ScenePlayerState, type MotionSetup } from '@senseihq/emaki';
package/dist/index.js ADDED
@@ -0,0 +1,3 @@
1
+ export { MotionScene, MotionShow, ScenePlayer, ShowPage } from './components.js';
2
+ export { useScenePlayer, usePlayerFor, useShowState } from './hooks.js';
3
+ export { setupMotion, ScenePlayerState } from '@senseihq/emaki';
package/package.json CHANGED
@@ -1,6 +1,45 @@
1
1
  {
2
2
  "name": "@senseihq/emaki-react",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "React components and hooks for motion stories: article figures, the story player, a controlled scene player and the video capture page.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "author": "SenecaGlobal",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/sensei-hq/emaki.git",
11
+ "directory": "packages/emaki-react"
12
+ },
13
+ "keywords": ["emaki", "react", "nextjs", "motion", "animation", "explainer", "i18n"],
14
+ "sideEffects": false,
15
+ "files": ["dist/**/*.js", "dist/**/*.d.ts", "src", "README.md", "LICENSE"],
16
+ "main": "./dist/index.js",
17
+ "types": "./dist/index.d.ts",
18
+ "exports": {
19
+ "./package.json": "./package.json",
20
+ ".": {
21
+ "types": "./dist/index.d.ts",
22
+ "import": "./dist/index.js"
23
+ }
24
+ },
25
+ "scripts": {
26
+ "build": "rm -rf dist && bunx tsc --project tsconfig.build.json",
27
+ "prepublishOnly": "cp ../../LICENSE . && bun run build",
28
+ "postpublish": "rm -f LICENSE"
29
+ },
30
+ "peerDependencies": {
31
+ "react": ">=18"
32
+ },
33
+ "dependencies": {
34
+ "@senseihq/emaki": "0.1.0"
35
+ },
36
+ "devDependencies": {
37
+ "@types/react": "^19.1.0",
38
+ "react": "^19.1.0",
39
+ "react-dom": "^19.1.0",
40
+ "@types/react-dom": "^19.1.0"
41
+ },
42
+ "publishConfig": {
43
+ "access": "public"
44
+ }
45
+ }
@@ -0,0 +1,119 @@
1
+ // React components over @senseihq/emaki. All are client components (they need the DOM); in Next.js import them
2
+ // from a file marked 'use client'. Call setupMotion({ source, site, logos }) once on the client first.
3
+ import { useEffect, useRef, useState, type CSSProperties } from 'react';
4
+ import { attachScene, createShow, installCapture, type AttachedScene, type Layout, type Mode, type ScenePlayerState } from '@senseihq/emaki';
5
+ import { usePlayerFor, useScenePlayer, useShowState, useSize, useWidth, type Show } from './hooks.js';
6
+
7
+ /** Mounts a player's scene into a div and keeps it fitted (shared by MotionScene and ScenePlayer). */
8
+ function useAttached(player: ScenePlayerState, locale: string, mode: Mode, autoplay: boolean) {
9
+ const [ref, width] = useWidth<HTMLDivElement>();
10
+ const host = useRef<HTMLDivElement>(null);
11
+ const view = useRef<AttachedScene | null>(null);
12
+ useEffect(() => {
13
+ view.current = attachScene(host.current!, player, { locale, mode, autoplay });
14
+ return () => { view.current?.destroy(); view.current = null; };
15
+ }, [player]); // eslint-disable-line react-hooks/exhaustive-deps
16
+ useEffect(() => { view.current?.setLocale(locale); }, [locale]);
17
+ useEffect(() => { view.current?.setMode(mode); }, [mode]);
18
+ useEffect(() => { if (width) view.current?.fit(width); }, [width]);
19
+ return { ref, host };
20
+ }
21
+
22
+ export interface MotionSceneProps { film: string; scene: string; layout?: Layout; locale?: string; mode?: Mode; autoplay?: boolean; className?: string; style?: CSSProperties }
23
+
24
+ /** An article figure: one scene, looping while it is on screen. */
25
+ export function MotionScene({ film, scene, layout = 'figure', locale = 'en', mode = 'auto', autoplay = true, className, style }: MotionSceneProps) {
26
+ const player = usePlayerFor({ film, scene, layout });
27
+ const { ref, host } = useAttached(player, locale, mode, autoplay);
28
+ return <div ref={ref} className={className} style={{ width: '100%', ...style }}><div ref={host} /></div>;
29
+ }
30
+
31
+ export interface ScenePlayerProps { player: ScenePlayerState; locale?: string; mode?: Mode; controls?: boolean; className?: string }
32
+
33
+ /** A scene driven by a ScenePlayerState you own (editors, previews, step-throughs). */
34
+ export function ScenePlayer({ player, locale = 'en', mode = 'auto', controls = false, className }: ScenePlayerProps) {
35
+ const p = useScenePlayer(player);
36
+ const { ref, host } = useAttached(player, locale, mode, false);
37
+ const msg: CSSProperties = { position: 'absolute', inset: 0, display: 'grid', placeItems: 'center', margin: 0, font: '14px system-ui' };
38
+ return (
39
+ <div ref={ref} className={className} style={{ position: 'relative', width: '100%' }}>
40
+ <div ref={host} />
41
+ {p.status === 'error' && <p role="alert" style={{ ...msg, color: '#b42318' }}>{p.error}</p>}
42
+ {p.status === 'idle' && <p style={{ ...msg, opacity: 0.7 }}>Loading the scene…</p>}
43
+ {controls && p.status === 'ready' && (
44
+ <div style={{ display: 'flex', alignItems: 'center', gap: 12, marginTop: 10, font: '12px ui-monospace, monospace' }}>
45
+ <button onClick={() => p.toggle()} aria-label={p.playing ? 'Pause' : 'Play'}>{p.playing ? '❚❚' : '▶'}</button>
46
+ <input type="range" aria-label="Seek" min={0} max={p.dur} step={0.05} value={p.t} onChange={(e) => p.seek(Number(e.target.value))} style={{ flex: 1 }} />
47
+ <span>{p.t.toFixed(1)} / {p.dur.toFixed(1)}</span>
48
+ </div>
49
+ )}
50
+ </div>
51
+ );
52
+ }
53
+
54
+ export interface MotionShowProps {
55
+ film: string; locale?: string; layout?: Layout; mode?: Mode; controls?: boolean; slide?: number; loop?: boolean;
56
+ /** The controller once ready (next/prev/play/pause/setSound/setLayout/seek/on), for custom chrome. */
57
+ onReady?: (show: Show) => void;
58
+ className?: string; style?: CSSProperties;
59
+ }
60
+
61
+ /** The story player: a film's scenes as slides, fitted to its box. Keys: ←/→, Space, M (sound), O (orientation). */
62
+ export function MotionShow({ film, locale = 'en', layout = 'landscape', mode = 'auto', controls = true, slide = 1, loop = false, onReady, className, style }: MotionShowProps) {
63
+ const stage = useRef<HTMLDivElement>(null);
64
+ const [fitRef, size] = useSize<HTMLDivElement>();
65
+ const [show, setShow] = useState<Show | null>(null);
66
+ const st = useShowState(show);
67
+ useEffect(() => {
68
+ let alive = true, made: Show | null = null;
69
+ createShow(stage.current!, film, { locale, layout, mode, slide, loop }).then((s) => {
70
+ if (!alive) return s.destroy();
71
+ made = s; setShow(s); onReady?.(s);
72
+ });
73
+ return () => { alive = false; made?.destroy(); setShow(null); };
74
+ }, [film, locale, mode]); // eslint-disable-line react-hooks/exhaustive-deps
75
+ useEffect(() => { if (show && show.state.layout !== layout) show.setLayout(layout); }, [show, layout]);
76
+ useEffect(() => { show?.fit(size.w, size.h); }, [show, size, st?.layout]);
77
+ const onKeyDown = (e: React.KeyboardEvent) => {
78
+ if (!show) return;
79
+ const k = e.key.toLowerCase();
80
+ if (k === 'arrowright') show.next(); else if (k === 'arrowleft') show.prev();
81
+ else if (k === ' ') { show.toggle(); e.preventDefault(); }
82
+ else if (k === 'm') show.setSound(!show.state.sound);
83
+ else if (k === 'o') show.setLayout(show.state.layout === 'landscape' ? 'portrait' : 'landscape');
84
+ };
85
+ const btn: CSSProperties = { minWidth: 34, height: 34, borderRadius: 17, border: '1px solid currentColor', background: 'none', color: 'inherit', cursor: 'pointer', padding: '0 10px' };
86
+ return (
87
+ <div tabIndex={0} role="application" aria-label="Story player" onKeyDown={onKeyDown} className={className}
88
+ style={{ position: 'relative', width: '100%', height: '100%', display: 'flex', flexDirection: 'column', outline: 'none', ...style }}>
89
+ <div ref={fitRef} style={{ position: 'relative', flex: 1, minHeight: 0, display: 'grid', placeItems: 'center', overflow: 'hidden' }}>
90
+ <div ref={stage} style={{ position: 'relative' }} />
91
+ </div>
92
+ {controls && show && st && (
93
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center', justifyContent: 'center', padding: 8, font: '13px system-ui' }}>
94
+ <button style={btn} onClick={() => show.prev()} aria-label="Previous scene">‹</button>
95
+ <button style={btn} onClick={() => show.toggle()} aria-label={st.playing ? 'Pause' : 'Play'}>{st.playing ? '❚❚' : '▶'}</button>
96
+ <button style={btn} onClick={() => show.next()} aria-label="Next scene">›</button>
97
+ <span style={{ opacity: 0.7 }}>{st.index + 1} / {show.timeline.scenes.length}</span>
98
+ <button style={btn} onClick={() => show.setSound(!st.sound)} aria-pressed={st.sound}>{st.sound ? 'Sound on' : 'Sound off'}</button>
99
+ </div>
100
+ )}
101
+ </div>
102
+ );
103
+ }
104
+
105
+ /** mode: capture renders light unless asked; the interactive player follows the page (auto). */
106
+ export interface ShowPageProps { film: string; layout?: Layout; locale?: string; mode?: Mode; capture?: boolean }
107
+
108
+ /** The /show/<film> page the video pipeline drives: with `capture`, the stage at 1:1, no chrome, window.__show. */
109
+ export function ShowPage({ film, layout = 'landscape', locale = 'en', mode, capture = false }: ShowPageProps) {
110
+ const host = useRef<HTMLDivElement>(null);
111
+ useEffect(() => {
112
+ if (!capture) return;
113
+ let s: Show | null = null;
114
+ installCapture(host.current!, film, layout, locale, mode ?? 'light').then((x) => { s = x; });
115
+ return () => s?.destroy();
116
+ }, [capture, film, layout, locale, mode]);
117
+ if (capture) return <div ref={host} />;
118
+ return <div style={{ position: 'fixed', inset: 0 }}><MotionShow film={film} layout={layout} locale={locale} mode={mode ?? 'auto'} /></div>;
119
+ }
package/src/hooks.ts ADDED
@@ -0,0 +1,63 @@
1
+ // React state over the core: the core notifies, useSyncExternalStore re-renders. Nothing here touches the DOM.
2
+ import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
3
+ import { ScenePlayerState, type createShow, type Layout, type SceneRef } from '@senseihq/emaki';
4
+
5
+ /** Re-renders whenever the player changes; returns it for reads (p.t, p.playing, p.status) and calls (p.seek(2)). */
6
+ export function useScenePlayer(player: ScenePlayerState) {
7
+ useSyncExternalStore(
8
+ (cb) => player.subscribe(cb),
9
+ () => player.version,
10
+ () => player.version,
11
+ );
12
+ return player;
13
+ }
14
+
15
+ /** A player you own, created once and pointed at `ref` (reloads when film, scene or layout change). */
16
+ export function usePlayerFor(ref: SceneRef | null) {
17
+ const player = useMemo(() => new ScenePlayerState(), []);
18
+ const key = ref ? `${ref.film}:${ref.scene}:${ref.layout}:${ref.src ?? ''}` : '';
19
+ useEffect(() => { if (ref) player.load(ref); }, [key]); // eslint-disable-line react-hooks/exhaustive-deps
20
+ return useScenePlayer(player);
21
+ }
22
+
23
+ export type Show = Awaited<ReturnType<typeof createShow>>;
24
+ export interface ShowState { index: number; local: number; playing: boolean; sound: boolean; layout: Layout }
25
+
26
+ /** State of a story player controller (from <MotionShow onReady>): re-renders on scene, play, sound, layout changes. */
27
+ export function useShowState(show: Show | null): ShowState | null {
28
+ const [st, setSt] = useState<ShowState | null>(show ? show.state : null);
29
+ const last = useRef(show);
30
+ useEffect(() => {
31
+ last.current = show;
32
+ if (!show) return setSt(null);
33
+ setSt(show.state);
34
+ const off = show.on((s) => setSt({ ...s }));
35
+ return () => { off(); };
36
+ }, [show]);
37
+ return st;
38
+ }
39
+
40
+ /** Width of an element, tracked with a ResizeObserver. */
41
+ export function useWidth<T extends HTMLElement>() {
42
+ const ref = useRef<T>(null);
43
+ const [w, setW] = useState(0);
44
+ useEffect(() => {
45
+ if (!ref.current) return;
46
+ const ro = new ResizeObserver(([e]) => setW(e.contentRect.width));
47
+ ro.observe(ref.current);
48
+ return () => ro.disconnect();
49
+ }, []);
50
+ return [ref, w] as const;
51
+ }
52
+
53
+ export function useSize<T extends HTMLElement>() {
54
+ const ref = useRef<T>(null);
55
+ const [s, setS] = useState({ w: 0, h: 0 });
56
+ useEffect(() => {
57
+ if (!ref.current) return;
58
+ const ro = new ResizeObserver(([e]) => setS({ w: e.contentRect.width, h: e.contentRect.height }));
59
+ ro.observe(ref.current);
60
+ return () => ro.disconnect();
61
+ }, []);
62
+ return [ref, s] as const;
63
+ }
package/src/index.ts ADDED
@@ -0,0 +1,3 @@
1
+ export { MotionScene, MotionShow, ScenePlayer, ShowPage, type MotionSceneProps, type MotionShowProps, type ScenePlayerProps, type ShowPageProps } from './components.js';
2
+ export { useScenePlayer, usePlayerFor, useShowState, type Show, type ShowState } from './hooks.js';
3
+ export { setupMotion, ScenePlayerState, type MotionSetup } from '@senseihq/emaki';