@getnarro/atlas 0.1.0

package/dist/path-BIxJH8g2.d.ts

@@ -0,0 +1,101 @@
+import { V as View } from './view-BzztOpV6.js';
+
+/**
+ * The camera path: an ordered list of named framings, as data.
+ *
+ * A waypoint names a place, never an index. `TransformConfig.positions` is a
+ * `Map<string, SlidePosition>` keyed by slide index, and that is the second thing this
+ * package fixes: an index renumbers itself the moment somebody inserts a waypoint above
+ * it, and it cannot be a URL fragment, an export filename, or the thing a checklist item
+ * binds to. A name can be all four.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Where a waypoint looks.
+ *
+ * Either a framing in world units, or a **reference** the scene provider resolves — a
+ * CSS selector over a replay, a node id on a plane. A reference is the authorable form:
+ * `"#publish-button"` survives a re-record that moves the button, where the coordinates
+ * it resolved to last week do not.
+ */
+type WaypointTarget = View | string;
+/** One named framing on the path. */
+interface Waypoint {
+    /**
+     * A stable name, unique within the path.
+     *
+     * It is the URL fragment, the export filename and the binding a checklist item uses,
+     * so it outlives reordering in a way an index cannot.
+     */
+    id: string;
+    /** Where to look: a `{ cx, cy, w }` framing, or a reference for the provider. */
+    at: WaypointTarget;
+    /**
+     * How far the camera pulls back on the way *in* to this waypoint — van Wijk's ρ.
+     *
+     * @defaultValue {@link DEFAULT_RHO}
+     */
+    arc?: number;
+    /**
+     * How long the flight *in* to this waypoint takes, in **seconds**.
+     *
+     * Omit it and the flight uses its own `suggestedDuration`, which is derived from how
+     * far the picture actually travels. Overriding it is what `narro check` measures
+     * against that suggestion — an override far below it is the lurch, and far above it is
+     * the sixteen-minute camera move.
+     */
+    duration?: number;
+    /** How long to rest here before flying on, in seconds. Only autoplay and video use it. */
+    hold?: number;
+    /** Human-readable label, for a checklist, a progress rail or an export filename. */
+    label?: string;
+    /** A chapter in a `.narrocast`, for the replay provider. Ignored by other providers. */
+    chapter?: string;
+}
+/** A camera path over one scene. */
+interface AtlasPath {
+    waypoints: Waypoint[];
+    /** ρ for any waypoint that does not set its own. */
+    arc?: number;
+    /** `hold` for any waypoint that does not set its own. Seconds. */
+    hold?: number;
+}
+/** A waypoint whose target has been resolved to a concrete framing. */
+interface ResolvedWaypoint extends Omit<Waypoint, "at"> {
+    at: View;
+    /** The reference this came from, when it was authored as one. */
+    ref?: string;
+    /** Its position on the path. */
+    index: number;
+}
+/** Why a waypoint could not be resolved. */
+interface UnresolvedWaypoint {
+    id: string;
+    index: number;
+    ref: string;
+}
+interface ResolveResult {
+    resolved: ResolvedWaypoint[];
+    unresolved: UnresolvedWaypoint[];
+}
+/** Is this target a concrete framing rather than a reference for the provider? */
+declare function isView(target: WaypointTarget): target is View;
+/**
+ * Turn every waypoint's target into a framing, using `resolve` for the references.
+ *
+ * Unresolved waypoints are returned rather than thrown: the checker wants to report all
+ * of them at once, and a host wants to skip the broken one and still fly the rest.
+ */
+declare function resolvePath(path: AtlasPath, resolve: (ref: string) => View | null): ResolveResult;
+/** The ρ a waypoint flies in with, falling back to the path's and then the default. */
+declare function arcFor(path: AtlasPath, waypoint: Pick<Waypoint, "arc">): number;
+/** The rest a waypoint takes, falling back to the path's and then to none. */
+declare function holdFor(path: AtlasPath, waypoint: Pick<Waypoint, "hold">): number;
+/** Find a waypoint by name. */
+declare function waypointIndex(path: AtlasPath, id: string): number;
+/** Names used more than once, in the order they first repeat. */
+declare function duplicateIds(path: AtlasPath): string[];
+
+export { type AtlasPath as A, type ResolvedWaypoint as R, type UnresolvedWaypoint as U, type Waypoint as W, arcFor as a, type ResolveResult as b, type WaypointTarget as c, duplicateIds as d, holdFor as h, isView as i, resolvePath as r, waypointIndex as w };

package/dist/provider-CjL3i-0A.d.ts

@@ -0,0 +1,54 @@
+import { R as Rect, c as Viewport, V as View } from './view-BzztOpV6.js';
+
+/**
+ * One interface, so a deck, a video and a web page render four different kinds of scene
+ * the same way.
+ *
+ * The member that earns the interface is {@link SceneProvider.ready}. A plane is ready
+ * the instant it mounts, but a map has to fetch tiles and a replay has to reach a
+ * chapter — both over the network, both asynchronously. The video renderer advances a
+ * frame counter as fast as it can, so without a gate it will happily render frame 12 of
+ * a map that has not drawn anything yet and encode a video of grey squares. That failure
+ * is the single most likely way a spatial canvas ships broken, so the check for it is in
+ * the type rather than in a provider's good intentions.
+ *
+ * @packageDocumentation
+ */
+
+/** The providers this package knows about. A closed set, so `catalog.json` can carry it. */
+declare const PROVIDER_NAMES: readonly ["plane", "replay", "map", "image", "dom"];
+type ProviderName = (typeof PROVIDER_NAMES)[number];
+interface SceneProvider {
+    /** Which kind of scene this is. */
+    readonly name: ProviderName;
+    /**
+     * The world rectangle the scene occupies, or null when it does not know yet.
+     *
+     * The checker uses it to catch a waypoint that flies to somewhere there is nothing.
+     */
+    bounds(): Rect | null;
+    /**
+     * A waypoint reference — a CSS selector, a node id — resolved to a framing.
+     *
+     * Null when it matches nothing, which is a diagnostic rather than a crash: the host
+     * skips that waypoint and the checker reports it by name.
+     */
+    resolve(ref: string, viewport: Viewport): View | null;
+    /**
+     * Has everything this view needs finished loading?
+     *
+     * The video host holds the frame until this is true; the deck host ignores it, because
+     * a presenter can see perfectly well that the tiles have not arrived.
+     */
+    ready(view: View): boolean;
+    /**
+     * Put the view on screen itself.
+     *
+     * Return `true` when the provider has handled it — a map moves its own camera — and
+     * the host will not apply a CSS transform. Return `false`, or leave it undefined, and
+     * the host applies the one composited transform that is the default rendering model.
+     */
+    apply?(view: View, viewport: Viewport): boolean;
+}
+
+export { PROVIDER_NAMES as P, type SceneProvider as S, type ProviderName as a };

package/dist/react/index.d.ts

@@ -0,0 +1,183 @@
+import React from 'react';
+import { A as AtlasPath } from '../path-BIxJH8g2.js';
+import { c as Viewport, V as View } from '../view-BzztOpV6.js';
+import { P as PlacedNode } from '../lod-DBuZ0MG3.js';
+import { S as SceneProvider } from '../provider-CjL3i-0A.js';
+
+/**
+ * The deck host: one plane, one camera, one composited transform.
+ *
+ * @packageDocumentation
+ */
+
+interface AtlasContextValue {
+    /** Where the camera is this frame. */
+    view: View;
+    /** Is a flight in progress? */
+    flying: boolean;
+    /** Index of the waypoint the camera is at or heading for. */
+    index: number;
+    /** Its id, when there is one. */
+    waypointId: string | null;
+    total: number;
+    goTo: (indexOrId: number | string) => void;
+    next: () => void;
+    previous: () => void;
+}
+/**
+ * Read the camera from inside a scene.
+ *
+ * A checklist beside the canvas ticking as the camera arrives is this hook plus the
+ * waypoint ids, and nothing else.
+ */
+declare function useAtlas(): AtlasContextValue;
+interface AtlasProps {
+    /** The camera path. */
+    path: AtlasPath;
+    /** The scene. Defaults to a plane built from `nodes`. */
+    provider?: SceneProvider;
+    /** Nodes on the default plane. Ignored when `provider` is given. */
+    nodes?: readonly PlacedNode[];
+    /** What to render on the plane. Node ids come from `data-atlas-id`. */
+    children?: React.ReactNode;
+    /**
+     * The coordinate grid the world is measured in.
+     *
+     * This is the *world*, not the surface it is painted on: it fixes what `at: 0, 0, 4000`
+     * means, and it is what a reference resolves against. The actual pixel size of the
+     * canvas is measured, so a deck rendered at any size frames the same content.
+     *
+     * @defaultValue 1920x1080
+     */
+    viewport?: Viewport;
+    /** Which waypoint to start at. @defaultValue 0 */
+    initialWaypoint?: number | string;
+    /**
+     * Take the arrow keys.
+     *
+     * Uses the same contract as `Slide`'s sub-slides: capture the key, and swallow it only
+     * while there is another waypoint to move to, so the deck advances normally at either
+     * end. Without that, the deck and the canvas both act on one press.
+     *
+     * @defaultValue true
+     */
+    keyboard?: boolean;
+    /** Only listen while this is true — a deck passes its slide's `isActive`. @defaultValue true */
+    active?: boolean;
+    /** Called on arrival at each waypoint. */
+    onArrive?: (id: string, index: number) => void;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * A zooming canvas.
+ *
+ * ```tsx
+ * <Atlas path={{ waypoints: [
+ *   { id: "whole", at: { cx: 0, cy: 0, w: 4000 } },
+ *   { id: "ingest", at: "#ingest" },
+ * ] }} nodes={nodes}>
+ *   <div data-atlas-id="ingest">…</div>
+ * </Atlas>
+ * ```
+ *
+ * @behaviour Fills its container and clips to it, so it wants a slide of its own. Its
+ * children are placed in world units on a plane the camera moves over rather than laid out
+ * by the slide — `AtlasNode` is what places them — and a node the camera cannot see, or
+ * that its level-of-detail band excludes, is unmounted rather than merely hidden.
+ */
+declare function Atlas({ path, provider, nodes, children, viewport, initialWaypoint, keyboard, active, onArrive, className, style, }: AtlasProps): React.ReactElement;
+/**
+ * Is this node currently mounted?
+ *
+ * A node the scene never described — a backdrop, a caption, a progress rail — is always
+ * mounted. Culling is opt-in per node, so declaring `nodes` can never make content the
+ * author did not describe disappear.
+ */
+declare function useIsMounted(id: string | undefined): boolean;
+interface AtlasNodeProps {
+    /** Must match a `PlacedNode.id`, or the node is never culled. */
+    id: string;
+    /** Where it sits, in world units. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    children?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * A node on the plane.
+ *
+ * `contain: layout paint` is not decoration: it stops a node's own layout from escaping
+ * into the camera root, which is what keeps a frame at one style recalculation and zero
+ * layout however many nodes are mounted.
+ *
+ * @behaviour Positions itself absolutely at `x`/`y` in world units, so it only works
+ * inside an `Atlas` and ignores whatever layout surrounds it. It renders nothing at all
+ * while the camera cannot see it, or while its `lod` band excludes the current framing.
+ */
+declare function AtlasNode({ id, x, y, width, height, children, className, style, }: AtlasNodeProps): React.ReactElement | null;
+
+/**
+ * The camera as a hook: a target waypoint goes in, a view comes out every frame.
+ *
+ * Driven by `requestAnimationFrame` rather than by a CSS transition or a spring library,
+ * for three reasons. The flight is not a cubic bézier, so a CSS transition cannot express
+ * it. The view is needed in JavaScript anyway, because culling and level-of-detail are
+ * decided from it. And the same `flight` has to serve the video host, where there is no
+ * rAF at all — so the interpolation lives in a pure function and only the clock differs.
+ *
+ * @packageDocumentation
+ */
+
+/** Does this viewer want less motion? Re-read live, because they can change it mid-deck. */
+declare function usePrefersReducedMotion(): boolean;
+interface CameraState {
+    /** Where the camera is right now. */
+    view: View;
+    /** Is a flight in progress? The `will-change` switch keys off this. */
+    flying: boolean;
+}
+interface UseCameraOptions {
+    /** Where the camera should end up. */
+    target: View;
+    /** How long to take, in seconds. Omit and the flight's own suggestion is used. */
+    duration?: number;
+    /** van Wijk's ρ. */
+    arc?: number;
+    /** Cut instead of flying — what a reduced-motion viewer gets. */
+    cut?: boolean;
+    /** Called once the camera settles. */
+    onArrive?: () => void;
+}
+/**
+ * Fly the camera to `target` whenever it changes.
+ *
+ * A target that changes mid-flight is honoured immediately: the new flight starts from
+ * wherever the camera actually is, not from the waypoint it was heading for. A presenter
+ * who presses `→` twice quickly gets one continuous move, not a jump.
+ */
+declare function useCamera({ target, duration, arc, cut, onArrive, }: UseCameraOptions): CameraState;
+/**
+ * The `will-change` value for a camera root, and the reason it is not a constant.
+ *
+ * Chrome re-rasterises content when its transform scale changes — *unless* it carries
+ * `will-change: transform`, which is a promise to the compositor to apply the transform
+ * fast and skip the re-raster. That makes the property a straight trade:
+ *
+ * - always on → cheap frames, and permanently blurry after a zoom, because the texture
+ *   is still rasterised at whatever scale the layer was created at. This is the blur
+ *   reported against impress.js and against WebKit 3D transforms for a decade.
+ * - never set → sharp, and a re-raster of the whole subtree on every frame of a zoom.
+ *
+ * So switch it: on while flying, off on arrival. The blur then exists only during the
+ * move, when nobody is reading, and every resting frame — every frame anyone stops on,
+ * screenshots, or exports — is sharp.
+ */
+declare function cameraWillChange(flying: boolean): "transform" | "auto";
+/** Step to a waypoint index, clamped, without wrapping. */
+declare function clampIndex(index: number, length: number): number;
+
+export { Atlas, type AtlasContextValue, AtlasNode, type AtlasNodeProps, type AtlasProps, type CameraState, type UseCameraOptions, cameraWillChange, clampIndex, useAtlas, useCamera, useIsMounted, usePrefersReducedMotion };

package/dist/react/index.js

@@ -0,0 +1,291 @@
+import { planeProvider } from '../chunk-BDF2X5LC.js';
+import { visibleNodes } from '../chunk-5SRKWTOU.js';
+import { flight, resolvePath, arcFor } from '../chunk-RHTCDWZD.js';
+import { transformToCss, viewToTransform } from '../chunk-RWYOYDBD.js';
+import { createContext, useState, useEffect, useRef, useMemo, useContext } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+function usePrefersReducedMotion() {
+  const [reduced, setReduced] = useState(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return false;
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  });
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const query = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const onChange = (event) => setReduced(event.matches);
+    query.addEventListener("change", onChange);
+    return () => query.removeEventListener("change", onChange);
+  }, []);
+  return reduced;
+}
+function useCamera({
+  target,
+  duration,
+  arc,
+  cut = false,
+  onArrive
+}) {
+  const [view, setView] = useState(target);
+  const [flying, setFlying] = useState(false);
+  const viewRef = useRef(view);
+  viewRef.current = view;
+  const onArriveRef = useRef(onArrive);
+  onArriveRef.current = onArrive;
+  const { cx, cy, w } = target;
+  useEffect(() => {
+    const to = { cx, cy, w };
+    const from = viewRef.current;
+    if (from.cx === to.cx && from.cy === to.cy && from.w === to.w) {
+      return;
+    }
+    if (cut) {
+      setView(to);
+      setFlying(false);
+      onArriveRef.current?.();
+      return;
+    }
+    const path = flight(from, to, arc);
+    const seconds = duration ?? path.suggestedDuration;
+    if (seconds <= 0) {
+      setView(to);
+      onArriveRef.current?.();
+      return;
+    }
+    let raf = 0;
+    let start = null;
+    setFlying(true);
+    const step = (now) => {
+      if (start === null) start = now;
+      const t = Math.min(1, (now - start) / (seconds * 1e3));
+      setView(path.at(t));
+      if (t < 1) {
+        raf = requestAnimationFrame(step);
+      } else {
+        setFlying(false);
+        onArriveRef.current?.();
+      }
+    };
+    raf = requestAnimationFrame(step);
+    return () => {
+      cancelAnimationFrame(raf);
+      setFlying(false);
+    };
+  }, [cx, cy, w, cut, duration, arc]);
+  return useMemo(() => ({ view, flying }), [view, flying]);
+}
+function cameraWillChange(flying) {
+  return flying ? "transform" : "auto";
+}
+function clampIndex(index, length) {
+  if (length <= 0) return 0;
+  return Math.min(Math.max(index, 0), length - 1);
+}
+var DEFAULT_VIEWPORT = { width: 1920, height: 1080 };
+var AtlasContext = createContext(null);
+function useAtlas() {
+  const value = useContext(AtlasContext);
+  if (!value) throw new Error("useAtlas must be used inside an <Atlas>");
+  return value;
+}
+function Atlas({
+  path,
+  provider,
+  nodes = [],
+  children,
+  viewport = DEFAULT_VIEWPORT,
+  initialWaypoint = 0,
+  keyboard = true,
+  active = true,
+  onArrive,
+  className,
+  style
+}) {
+  const scene = useMemo(() => provider ?? planeProvider({ nodes }), [provider, nodes]);
+  const { resolved } = useMemo(
+    () => resolvePath(path, (ref) => scene.resolve(ref, viewport)),
+    [path, scene, viewport]
+  );
+  const startIndex = useMemo(() => {
+    if (typeof initialWaypoint === "string") {
+      const found = resolved.findIndex((w) => w.id === initialWaypoint);
+      return found === -1 ? 0 : found;
+    }
+    return clampIndex(initialWaypoint, resolved.length);
+  }, [initialWaypoint, resolved]);
+  const rootRef = useRef(null);
+  const [painted, setPainted] = useState(null);
+  useEffect(() => {
+    const element = rootRef.current;
+    if (!element) return;
+    const measure = () => {
+      const width = element.offsetWidth;
+      const height = element.offsetHeight;
+      if (width <= 0 || height <= 0) return;
+      setPainted(
+        (previous) => previous && previous.width === width && previous.height === height ? previous : { width, height }
+      );
+    };
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+  const surface = painted ?? viewport;
+  const [index, setIndex] = useState(startIndex);
+  const safeIndex = clampIndex(index, resolved.length);
+  const current = resolved[safeIndex];
+  const reduced = usePrefersReducedMotion();
+  const target = current?.at ?? { cx: 0, cy: 0, w: viewport.width };
+  const { view, flying } = useCamera({
+    target,
+    duration: current?.duration,
+    arc: current ? arcFor(path, current) : void 0,
+    cut: reduced,
+    onArrive: () => {
+      if (current) onArrive?.(current.id, safeIndex);
+    }
+  });
+  useEffect(() => {
+    if (!keyboard || !active || resolved.length === 0) return;
+    const onKeyDown = (event) => {
+      if (event.ctrlKey || event.metaKey) return;
+      const target2 = event.target;
+      if (target2 && (target2.tagName === "INPUT" || target2.tagName === "TEXTAREA" || target2.isContentEditable)) {
+        return;
+      }
+      const forward = event.key === "ArrowRight" || event.key === " " || event.key === "Enter";
+      const back = event.key === "ArrowLeft";
+      if (forward && safeIndex < resolved.length - 1) {
+        event.preventDefault();
+        event.stopPropagation();
+        setIndex(safeIndex + 1);
+      } else if (back && safeIndex > 0) {
+        event.preventDefault();
+        event.stopPropagation();
+        setIndex(safeIndex - 1);
+      } else if (event.key === "Home") {
+        event.preventDefault();
+        event.stopPropagation();
+        setIndex(0);
+      } else if (event.key === "End") {
+        event.preventDefault();
+        event.stopPropagation();
+        setIndex(resolved.length - 1);
+      }
+    };
+    window.addEventListener("keydown", onKeyDown, { capture: true });
+    return () => window.removeEventListener("keydown", onKeyDown, { capture: true });
+  }, [keyboard, active, safeIndex, resolved.length]);
+  const keep = useMemo(() => {
+    const ids = /* @__PURE__ */ new Set();
+    for (const offset of [-1, 0, 1]) {
+      const w = resolved[safeIndex + offset];
+      if (w?.ref) ids.add(w.ref.startsWith("#") ? w.ref.slice(1) : w.ref);
+    }
+    return ids;
+  }, [resolved, safeIndex]);
+  const mounted = useMemo(
+    () => new Set(visibleNodes(nodes, view, viewport, { keep }).map((n) => n.id)),
+    [nodes, view, viewport, keep]
+  );
+  const handled = scene.apply?.(view, surface) ?? false;
+  const transform = handled ? void 0 : transformToCss(viewToTransform(view, surface));
+  const context = useMemo(
+    () => ({
+      view,
+      flying,
+      index: safeIndex,
+      waypointId: current?.id ?? null,
+      total: resolved.length,
+      goTo: (indexOrId) => {
+        const next = typeof indexOrId === "string" ? resolved.findIndex((w) => w.id === indexOrId) : indexOrId;
+        if (next >= 0) setIndex(clampIndex(next, resolved.length));
+      },
+      next: () => setIndex((i) => clampIndex(i + 1, resolved.length)),
+      previous: () => setIndex((i) => clampIndex(i - 1, resolved.length))
+    }),
+    [view, flying, safeIndex, current, resolved]
+  );
+  return /* @__PURE__ */ jsx(AtlasContext.Provider, { value: context, children: /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: rootRef,
+      className,
+      style: {
+        position: "relative",
+        width: "100%",
+        height: "100%",
+        overflow: "hidden",
+        ...style
+      },
+      children: /* @__PURE__ */ jsx(
+        "div",
+        {
+          "data-atlas-camera": "",
+          style: {
+            position: "absolute",
+            inset: 0,
+            transform,
+            transformOrigin: "0 0",
+            // On while flying, off on arrival — see `cameraWillChange`. This one line is
+            // the difference between text that is sharp at rest and text that never is.
+            willChange: cameraWillChange(flying)
+          },
+          children: /* @__PURE__ */ jsx(MountedNodes, { mounted, nodes, children })
+        }
+      )
+    }
+  ) });
+}
+var MountedContext = createContext(null);
+function MountedNodes({
+  mounted,
+  nodes,
+  children
+}) {
+  const declared = useMemo(() => new Set(nodes.map((n) => n.id)), [nodes]);
+  const value = useMemo(() => ({ mounted, declared }), [mounted, declared]);
+  return /* @__PURE__ */ jsx(MountedContext.Provider, { value, children });
+}
+function useIsMounted(id) {
+  const culling = useContext(MountedContext);
+  if (!culling || !id) return true;
+  if (!culling.declared.has(id)) return true;
+  return culling.mounted.has(id);
+}
+function AtlasNode({
+  id,
+  x,
+  y,
+  width,
+  height,
+  children,
+  className,
+  style
+}) {
+  const mounted = useIsMounted(id);
+  if (!mounted) return null;
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      "data-atlas-id": id,
+      className,
+      style: {
+        position: "absolute",
+        left: x,
+        top: y,
+        width,
+        height,
+        contain: "layout paint",
+        ...style
+      },
+      children
+    }
+  );
+}
+
+export { Atlas, AtlasNode, cameraWillChange, clampIndex, useAtlas, useCamera, useIsMounted, usePrefersReducedMotion };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map