@entrancekit/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 terminalis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @entrancekit/react
+
+> Turn an intro animation you already have — a video, a Lottie file, or your own React
+> component — into a **correct** app entrance, without writing the lifecycle yourself.
+
+The animation is the easy part. The flow around it is not: playing it on load without
+blocking the app, honoring reduced motion, falling back on slow or failed loads, exiting by
+the model you chose, and tearing down cleanly. **EntranceKit owns that flow. You keep owning
+the animation.**
+
+- **Non-blocking** — the overlay never gates your app; it stays interactive underneath.
+- **Reduced-motion aware** — `prefers-reduced-motion` is honored by default (no flash).
+- **Graceful** — skips on error, falls back on timeout, never traps the user.
+- **Self-removing** — deterministic teardown on every exit path, with an optional outro.
+- **Bring your own** — MP4/WebM, Lottie JSON, or any custom React/Motion/GSAP/Canvas/SVG
+  component. Client-only, single package, **zero runtime dependencies**, SSR-safe.
+
+## Install
+
+```sh
+npm install @entrancekit/react
+# Lottie support is optional and lazy-loaded:
+npm install @lottiefiles/dotlottie-react
+```
+
+## Drop in a video
+
+```tsx
+import { EntranceVideo } from '@entrancekit/react';
+
+export default function Root() {
+  return (
+    <>
+      <App /> {/* renders and stays interactive the whole time */}
+      <EntranceVideo
+        id="launch"
+        sources={[
+          { src: '/intro.webm', type: 'video/webm' },
+          { src: '/intro.mp4', type: 'video/mp4' },
+        ]}
+        poster="/intro-poster.png"
+        fallbackAfter={2500}
+      />
+    </>
+  );
+}
+```
+
+## Bring your own component (the core)
+
+```tsx
+import { EntranceController } from '@entrancekit/react';
+
+<EntranceController id="launch">
+  {({ shouldAnimate, complete, skip }) => (
+    <MyIntro
+      play={shouldAnimate}     // start when told
+      onComplete={complete}    // its OWN done-signal — the preferred path
+      onError={skip}           // never trap the user
+    />
+  )}
+</EntranceController>;
+```
+
+## The lifecycle
+
+EntranceKit owns one canonical state machine:
+
+```
+idle → preload → play → resolve → done
+```
+
+Every way an entrance can end — the animation's own done-signal, a user skip, a timeout, an
+error, or a reduced-motion suppression — funnels through a single `resolve` carrying a
+`reason`, so teardown is deterministic on every path. Wire your animation's native end event
+to `complete()`; `fallbackAfter` is only a safety net for a hung or slow load, never a cap on
+a correctly-signalling animation.
+
+## API at a glance
+
+| Export               | What it is                                                            |
+| -------------------- | -------------------------------------------------------------------- |
+| `EntranceController` | Render-prop for a bring-your-own animation. The core.                |
+| `EntranceVideo`      | MP4/WebM convenience entry point (prefers native `ended`).           |
+| `EntranceLottie`     | Lottie JSON entry point (optional, lazy-loaded player).              |
+| `useEntrance`        | The same engine, headless, for a fully custom overlay.               |
+
+Shared props: `id` (required), `fallbackAfter` (default `4000`), `reducedMotion`
+(`'skip'` \| `'play'`, default `'skip'`), `skipControl` (`true` \| render-fn \| `false`),
+`outro` (`number` \| `{ durationMs, render }`), `container`, and
+`onResolve` / `onError` / `onStateChange`.
+
+> There is no `mode`, no persistence, and no show-policy in v0.1.0 — an entrance is a
+> transient overlay that plays and leaves, not a once-per-user gate.
+
+## Demo
+
+A live Playground (every source, every scenario, every exit model) is at
+**[terminalis.github.io/entrancekit](https://terminalis.github.io/entrancekit/)** (deployed by
+CI from [`examples/demo`](./examples/demo)). Run it locally:
+
+```sh
+npm install && npm run build
+npm --prefix examples/demo install
+npm --prefix examples/demo run dev
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,556 @@
+"use client";
+'use strict';
+
+var react = require('react');
+var reactDom = require('react-dom');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/useEntrance.ts
+
+// src/lifecycle/reducer.ts
+var ACTIVE_PHASES = ["idle", "preload", "play"];
+var GRACEFUL_REASONS = ["completed", "skipped", "timeout"];
+var isActive = (phase) => ACTIVE_PHASES.includes(phase);
+function makeResolve(reason, error = null) {
+  return { phase: "resolve", reason, error };
+}
+var initialMachineState = {
+  phase: "idle",
+  reason: null,
+  error: null
+};
+function shouldRunOutro(reason, hasOutro) {
+  return hasOutro && GRACEFUL_REASONS.includes(reason);
+}
+function entranceReducer(state, action) {
+  switch (action.type) {
+    case "BEGIN":
+      return state.phase === "idle" ? { ...state, phase: "preload" } : state;
+    case "PRELOADED":
+      return state.phase === "preload" ? { ...state, phase: "play" } : state;
+    case "COMPLETE":
+      return state.phase === "preload" || state.phase === "play" ? makeResolve("completed") : state;
+    case "SKIP":
+      return state.phase === "preload" || state.phase === "play" ? makeResolve("skipped") : state;
+    case "TIMEOUT":
+      return state.phase === "preload" || state.phase === "play" ? makeResolve("timeout") : state;
+    case "FAIL":
+      return state.phase === "preload" || state.phase === "play" ? makeResolve("error", {
+        kind: action.kind ?? "unknown",
+        cause: action.cause
+      }) : state;
+    case "REDUCED_MOTION":
+      return isActive(state.phase) ? makeResolve("reduced-motion") : state;
+    case "ENTER_OUTRO":
+      return state.phase === "resolve" ? { ...state, phase: "outro" } : state;
+    case "ENTER_DONE":
+      return state.phase === "resolve" || state.phase === "outro" ? { ...state, phase: "done" } : state;
+    default: {
+      return state;
+    }
+  }
+}
+
+// src/lifecycle/reducedMotion.ts
+var QUERY = "(prefers-reduced-motion: reduce)";
+function getMediaQueryList() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return null;
+  }
+  try {
+    return window.matchMedia(QUERY);
+  } catch {
+    return null;
+  }
+}
+function prefersReducedMotion() {
+  return getMediaQueryList()?.matches ?? false;
+}
+function subscribeReducedMotion(onChange) {
+  const mql = getMediaQueryList();
+  if (!mql) return () => {
+  };
+  const handler = (event) => onChange(event.matches);
+  if (typeof mql.addEventListener === "function") {
+    mql.addEventListener("change", handler);
+    return () => mql.removeEventListener("change", handler);
+  }
+  const legacy = mql;
+  legacy.addListener?.(handler);
+  return () => legacy.removeListener?.(handler);
+}
+
+// src/lifecycle/useEntranceMachine.ts
+function useEntranceMachine(config) {
+  const [state, dispatch] = react.useReducer(entranceReducer, initialMachineState);
+  const { phase, reason } = state;
+  const { reducedMotion, fallbackAfter, preloadTimeout, outroTimeout, hasOutro } = config;
+  const actions = react.useMemo(
+    () => ({
+      preloaded: () => dispatch({ type: "PRELOADED" }),
+      complete: () => dispatch({ type: "COMPLETE" }),
+      skip: () => dispatch({ type: "SKIP" }),
+      fail: (kind, cause) => dispatch({ type: "FAIL", kind, cause }),
+      outroComplete: () => dispatch({ type: "ENTER_DONE" })
+    }),
+    []
+  );
+  react.useEffect(() => {
+    if (reducedMotion === "skip" && prefersReducedMotion()) {
+      dispatch({ type: "REDUCED_MOTION" });
+    } else {
+      dispatch({ type: "BEGIN" });
+    }
+    if (reducedMotion !== "skip") return;
+    return subscribeReducedMotion((reduced) => {
+      if (reduced) dispatch({ type: "REDUCED_MOTION" });
+    });
+  }, [reducedMotion]);
+  react.useEffect(() => {
+    let id;
+    if (phase === "preload") {
+      id = setTimeout(() => dispatch({ type: "TIMEOUT" }), preloadTimeout);
+    } else if (phase === "play") {
+      id = setTimeout(() => dispatch({ type: "TIMEOUT" }), fallbackAfter);
+    } else if (phase === "outro") {
+      id = setTimeout(() => dispatch({ type: "ENTER_DONE" }), outroTimeout);
+    }
+    return () => {
+      if (id !== void 0) clearTimeout(id);
+    };
+  }, [phase, preloadTimeout, fallbackAfter, outroTimeout]);
+  react.useEffect(() => {
+    if (phase !== "resolve" || reason === null) return;
+    dispatch(
+      shouldRunOutro(reason, hasOutro) ? { type: "ENTER_OUTRO" } : { type: "ENTER_DONE" }
+    );
+  }, [phase, reason, hasOutro]);
+  return { state, actions };
+}
+
+// src/lifecycle/defaults.ts
+var DEFAULT_FALLBACK_AFTER = 4e3;
+var DEFAULT_OUTRO_TIMEOUT = 1500;
+var DEFAULT_REDUCED_MOTION = "skip";
+function resolveConfig(input = {}) {
+  const fallbackAfter = input.fallbackAfter ?? DEFAULT_FALLBACK_AFTER;
+  return {
+    fallbackAfter,
+    preloadTimeout: input.preloadTimeout ?? fallbackAfter,
+    outroTimeout: input.outroTimeout ?? DEFAULT_OUTRO_TIMEOUT,
+    reducedMotion: input.reducedMotion ?? DEFAULT_REDUCED_MOTION,
+    hasOutro: input.hasOutro ?? false
+  };
+}
+
+// src/internal/config.ts
+function normalizeOutro(outro) {
+  if (outro == null) return { hasOutro: false, durationMs: DEFAULT_OUTRO_TIMEOUT };
+  if (typeof outro === "number") return { hasOutro: true, durationMs: outro };
+  return { hasOutro: true, durationMs: outro.durationMs, render: outro.render };
+}
+function configFromOptions(input) {
+  const outro = normalizeOutro(input.outro);
+  return resolveConfig({
+    fallbackAfter: input.fallbackAfter,
+    reducedMotion: input.reducedMotion,
+    hasOutro: outro.hasOutro,
+    outroTimeout: outro.durationMs
+  });
+}
+
+// src/internal/deriveRenderProps.ts
+function deriveRenderProps(state, actions) {
+  const { phase, reason } = state;
+  return {
+    // The transient `outro` phase is surfaced publicly as `'resolve'`.
+    state: phase === "outro" ? "resolve" : phase,
+    reason,
+    shouldAnimate: phase === "play",
+    shouldPlayOutro: phase === "outro",
+    isOverlayMounted: phase !== "done",
+    isPlaying: phase === "play",
+    isDone: phase === "done",
+    complete: actions.complete,
+    skip: actions.skip,
+    // Public error path: kind defaults to 'unknown'; the wrappers classify their
+    // own errors (load vs playback) via the raw machine action instead.
+    fail: (error) => actions.fail(void 0, error),
+    outroComplete: actions.outroComplete
+  };
+}
+function useEntranceCallbacks(id, state, { onResolve, onError, onStateChange }) {
+  const resolveFired = react.useRef(false);
+  react.useEffect(() => {
+    if (state.reason === null || resolveFired.current) return;
+    resolveFired.current = true;
+    onResolve?.({ id, reason: state.reason });
+    if (state.reason === "error") {
+      onError?.({ id, kind: state.error?.kind ?? "unknown", cause: state.error?.cause });
+    }
+  }, [state.reason, state.error, id, onResolve, onError]);
+  const publicState = state.phase === "outro" ? "resolve" : state.phase;
+  const lastState = react.useRef(null);
+  react.useEffect(() => {
+    if (lastState.current === publicState) return;
+    lastState.current = publicState;
+    onStateChange?.(publicState);
+  }, [publicState, onStateChange]);
+}
+
+// src/useEntrance.ts
+function useEntrance(options) {
+  const { id, fallbackAfter, reducedMotion, outro, onResolve, onError, onStateChange } = options;
+  const config = configFromOptions({ fallbackAfter, reducedMotion, outro });
+  const { state, actions } = useEntranceMachine(config);
+  react.useEffect(() => {
+    actions.preloaded();
+  }, [actions]);
+  useEntranceCallbacks(id, state, { onResolve, onError, onStateChange });
+  return deriveRenderProps(state, actions);
+}
+var emptySubscribe = () => () => {
+};
+function useIsClient() {
+  return react.useSyncExternalStore(
+    emptySubscribe,
+    () => true,
+    // client snapshot
+    () => false
+    // server / first-render snapshot
+  );
+}
+function useOverlayHost({
+  enabled,
+  container,
+  zIndex
+}) {
+  const [host, setHost] = react.useState(null);
+  react.useEffect(() => {
+    if (!enabled) {
+      setHost(null);
+      return;
+    }
+    if (container) {
+      setHost(container);
+      return;
+    }
+    const el = document.createElement("div");
+    el.setAttribute("data-entrancekit-host", "");
+    el.style.position = "fixed";
+    el.style.inset = "0";
+    el.style.pointerEvents = "none";
+    el.style.zIndex = zIndex !== void 0 ? String(zIndex) : "var(--entrancekit-z, 2147483647)";
+    document.body.appendChild(el);
+    setHost(el);
+    return () => {
+      el.remove();
+      setHost(null);
+    };
+  }, [enabled, container, zIndex]);
+  return host;
+}
+var DEFAULT_SKIP_LABEL = "Skip intro";
+var defaultSkipStyle = {
+  position: "absolute",
+  top: 16,
+  right: 16,
+  pointerEvents: "auto",
+  padding: "6px 12px",
+  font: "inherit",
+  fontSize: 14,
+  lineHeight: 1.2,
+  color: "#fff",
+  background: "rgba(0, 0, 0, 0.55)",
+  border: "1px solid rgba(255, 255, 255, 0.35)",
+  borderRadius: 6,
+  cursor: "pointer"
+};
+function EntranceOverlay({
+  api,
+  children,
+  outro,
+  skipControl = true,
+  skipLabel = DEFAULT_SKIP_LABEL,
+  zIndex,
+  container,
+  className,
+  style
+}) {
+  const isClient = useIsClient();
+  const host = useOverlayHost({
+    enabled: isClient && api.isOverlayMounted,
+    container,
+    zIndex
+  });
+  const previouslyFocused = react.useRef(null);
+  react.useEffect(() => {
+    previouslyFocused.current = document.activeElement;
+    return () => {
+      const prev = previouslyFocused.current;
+      const active = document.activeElement;
+      if (prev instanceof HTMLElement && active instanceof HTMLElement && active.closest("[data-entrancekit-overlay]")) {
+        prev.focus();
+      }
+    };
+  }, []);
+  if (!isClient || !host || !api.isOverlayMounted) return null;
+  const showVisuals = api.state !== "idle" && api.reason !== "reduced-motion";
+  const showSkip = skipControl !== false && (api.state === "preload" || api.state === "play");
+  const stageStyle = {
+    position: "absolute",
+    inset: 0,
+    pointerEvents: "none",
+    opacity: api.shouldPlayOutro ? 0 : 1,
+    transition: api.shouldPlayOutro ? `opacity ${outro.durationMs}ms ease` : void 0,
+    ...style
+  };
+  const visuals = api.shouldPlayOutro && outro.render && api.reason ? outro.render({ reason: api.reason }) : children;
+  return reactDom.createPortal(
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { "data-entrancekit-overlay": "", className, style: stageStyle, children: [
+      showVisuals && /* @__PURE__ */ jsxRuntime.jsx("div", { "aria-hidden": "true", style: { position: "absolute", inset: 0 }, children: visuals }),
+      showSkip && (typeof skipControl === "function" ? skipControl(api.skip) : /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          type: "button",
+          onClick: api.skip,
+          "aria-label": skipLabel,
+          "data-entrancekit-skip": "",
+          style: defaultSkipStyle,
+          children: skipLabel
+        }
+      ))
+    ] }),
+    host
+  );
+}
+function EntranceController(props) {
+  const {
+    children,
+    skipControl,
+    skipLabel,
+    zIndex,
+    container,
+    className,
+    style,
+    ...lifecycle
+  } = props;
+  const api = useEntrance(lifecycle);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    EntranceOverlay,
+    {
+      api,
+      outro: normalizeOutro(props.outro),
+      skipControl,
+      skipLabel,
+      zIndex,
+      container,
+      className,
+      style,
+      children: children(api)
+    }
+  );
+}
+
+// src/internal/useEntranceEngine.ts
+function useEntranceEngine(options) {
+  const config = configFromOptions(options);
+  const { state, actions } = useEntranceMachine(config);
+  useEntranceCallbacks(options.id, state, options);
+  return { state, actions, api: deriveRenderProps(state, actions) };
+}
+var videoStyle = {
+  position: "absolute",
+  inset: 0,
+  width: "100%",
+  height: "100%",
+  objectFit: "cover",
+  display: "block"
+};
+function EntranceVideo(props) {
+  const {
+    id,
+    src,
+    sources,
+    poster,
+    muted = true,
+    playsInline = true,
+    preload = "auto",
+    fallbackAfter,
+    reducedMotion,
+    outro,
+    skipControl,
+    skipLabel,
+    zIndex,
+    container,
+    className,
+    style,
+    onResolve,
+    onError,
+    onStateChange
+  } = props;
+  const { state, actions, api } = useEntranceEngine({
+    id,
+    fallbackAfter,
+    reducedMotion,
+    outro,
+    onResolve,
+    onError,
+    onStateChange
+  });
+  const videoRef = react.useRef(null);
+  const endedFired = react.useRef(false);
+  react.useEffect(() => {
+    if (state.phase !== "play") return;
+    const video = videoRef.current;
+    if (!video) return;
+    try {
+      video.muted = muted;
+      const result = video.play();
+      if (result && typeof result.then === "function") {
+        result.catch((err) => actions.fail("playback", err));
+      }
+    } catch (err) {
+      actions.fail("playback", err);
+    }
+  }, [state.phase, actions, muted]);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    EntranceOverlay,
+    {
+      api,
+      outro: normalizeOutro(outro),
+      skipControl,
+      skipLabel,
+      zIndex,
+      container,
+      className,
+      style,
+      children: /* @__PURE__ */ jsxRuntime.jsx(
+        "video",
+        {
+          ref: videoRef,
+          ...src ? { src } : {},
+          poster,
+          muted,
+          playsInline,
+          preload,
+          onCanPlayThrough: () => actions.preloaded(),
+          onLoadedData: () => actions.preloaded(),
+          onEnded: () => {
+            if (endedFired.current) return;
+            endedFired.current = true;
+            actions.complete();
+          },
+          onError: () => actions.fail("load"),
+          style: videoStyle,
+          children: sources?.map((source) => /* @__PURE__ */ jsxRuntime.jsx("source", { src: source.src, type: source.type }, source.src))
+        }
+      )
+    }
+  );
+}
+var PEER = "@lottiefiles/dotlottie-react";
+var playerStyle = {
+  position: "absolute",
+  inset: 0,
+  width: "100%",
+  height: "100%",
+  display: "block"
+};
+function EntranceLottie(props) {
+  const {
+    id,
+    src,
+    animationData,
+    onComplete,
+    fallbackAfter,
+    reducedMotion,
+    outro,
+    skipControl,
+    skipLabel,
+    zIndex,
+    container,
+    className,
+    style,
+    onResolve,
+    onError,
+    onStateChange
+  } = props;
+  const { state, actions, api } = useEntranceEngine({
+    id,
+    fallbackAfter,
+    reducedMotion,
+    outro,
+    onResolve,
+    onError,
+    onStateChange
+  });
+  const [Player, setPlayer] = react.useState(null);
+  const shouldLoad = state.phase === "preload" || state.phase === "play";
+  react.useEffect(() => {
+    if (!shouldLoad) return;
+    let alive = true;
+    const reportMissingPeer = (err) => {
+      if (typeof console !== "undefined") {
+        console.error(
+          `[EntranceKit] EntranceLottie requires the optional peer "${PEER}". Install it with: npm i ${PEER}`
+        );
+      }
+      actions.fail("missing-peer", err);
+    };
+    import('@lottiefiles/dotlottie-react').then((mod) => {
+      if (!alive) return;
+      const Comp = mod.DotLottieReact;
+      if (Comp) setPlayer(() => Comp);
+      else reportMissingPeer(new Error(`${PEER} did not export DotLottieReact`));
+    }).catch((err) => {
+      if (alive) reportMissingPeer(err);
+    });
+    return () => {
+      alive = false;
+    };
+  }, [shouldLoad, actions]);
+  const handleRef = react.useCallback(
+    (instance) => {
+      if (!instance) return;
+      instance.addEventListener("load", () => actions.preloaded());
+      instance.addEventListener("complete", () => {
+        actions.complete();
+        onComplete?.();
+      });
+      instance.addEventListener("loadError", () => actions.fail("load"));
+    },
+    [actions, onComplete]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    EntranceOverlay,
+    {
+      api,
+      outro: normalizeOutro(outro),
+      skipControl,
+      skipLabel,
+      zIndex,
+      container,
+      className,
+      style,
+      children: Player ? /* @__PURE__ */ jsxRuntime.jsx(
+        Player,
+        {
+          ...src ? { src } : {},
+          data: animationData,
+          loop: false,
+          autoplay: true,
+          dotLottieRefCallback: handleRef,
+          style: playerStyle
+        }
+      ) : null
+    }
+  );
+}
+
+exports.EntranceController = EntranceController;
+exports.EntranceLottie = EntranceLottie;
+exports.EntranceVideo = EntranceVideo;
+exports.useEntrance = useEntrance;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map