Cuelens

Cuelens (@wibus/cuelens) is a typed runtime for interactive product films. One playhead drives numeric tracks, narrative beats, camera shots, and host-owned cues against real DOM UI.

The package is a director, not a scene renderer. Your application owns the product UI, fixtures, audio, cursor, commands, and navigation. The runtime owns deterministic time, state derivation, cue replay rules, and camera framing.

Install

pnpm add @wibus/cuelens

React is a peer dependency. React hosts use the separate React entry:

pnpm add react @wibus/cuelens

AI install prompt:

Install @wibus/cuelens in this project, then read node_modules/@wibus/cuelens/install.md and node_modules/@wibus/cuelens/dist/docs/usage.md before integrating the appropriate runtime mode into the existing UI.

Choose a mode

Mode	Use it when	Main API
Automatic timeline	Playback, seeking, tracks, beats, and cues follow one clock.	defineSequence(), SequenceProvider, useSequenceFrame(), useSequenceCamera()
Host-controlled steps	A wizard, form, or onboarding flow decides when the shot changes.	defineSequenceSteps(), SequenceStepProvider, useSequenceStep(), useSequenceStepCamera()
Core only	A non-React host needs timing, cue, or camera primitives.	Root export only
Interaction triggers	Hover, focus, or click drives product actions and camera shots independently of progress.	defineSequenceTriggers(), useSequenceTriggers(), useCameraShot()

Minimal automatic sequence

import { defineSequence, cameraAnchorProps } from '@wibus/cuelens';
import {
  SequenceProvider,
  useSequenceCamera,
  useSequenceClock,
  useSequenceClockSnapshot,
  useSequenceFrame,
} from '@wibus/cuelens/react';
import { useRef } from 'react';

const sequence = defineSequence({
  duration: 8,
  tracks: {
    rows: [
      { time: 0, value: 1 },
      { time: 5, value: 4, easing: 'easeOutCubic' },
    ],
  },
  beats: [
    { id: 'wide', at: 0, title: 'Workspace', shot: { anchor: 'window' } },
    {
      id: 'write',
      at: 3,
      title: 'Composer',
      shot: { anchor: 'composer', maxScale: 1.5, yaw: -14, pitch: 5 },
    },
  ],
  cues: [{ id: 'send', at: 5.5, anchor: 'send', kind: 'press' }],
});

function Stage() {
  const viewportRef = useRef<HTMLDivElement>(null);
  const stageRef = useRef<HTMLDivElement>(null);
  const clock = useSequenceClock();
  const snapshot = useSequenceClockSnapshot();
  const frame = useSequenceFrame();

  useSequenceCamera({
    viewportRef,
    stageRef,
    fallbackRect: { x: 0, y: 0, width: 1600, height: 1000 },
    hideUntilReady: true,
  });

  return (
    <div ref={viewportRef} style={{ position: 'relative', overflow: 'clip' }}>
      <div ref={stageRef} style={{ width: 1600, height: 1000 }}>
        <main {...cameraAnchorProps('window')}>
          <textarea {...cameraAnchorProps('composer')} />
          <button {...cameraAnchorProps('send')}>Send</button>
          <output>{Math.floor(frame.values.rows)} rows</output>
        </main>
      </div>
      <button onClick={snapshot.playing ? clock.pause : clock.play}>
        {snapshot.playing ? 'Pause' : 'Play'}
      </button>
    </div>
  );
}

export function Demo() {
  return (
    <SequenceProvider definition={sequence} autoPlay={false}>
      <Stage />
    </SequenceProvider>
  );
}

Documentation

Document	Purpose
install.md	Installation workflow for developers and coding agents.
docs/usage.md	Authoritative installation, automatic and step modes, camera lifecycle, cues, performance, and testing guide.
docs/architecture/cuelens.md	Runtime boundaries, data flow, camera design, and future Creator architecture.
playground/	Independent Vite app for guided shots, timeline playback, JSON authoring, and camera diagnostics.
CONTRIBUTING.md	Local setup, project boundaries, tests, and pull request expectations.
CODE_OF_CONDUCT.md	Community participation and enforcement standards.
SECURITY.md	Supported releases and private vulnerability reporting.
RELEASING.md	Maintainer-only npm and GitHub release procedure.

Published packages include this documentation under dist/docs/. An AI or developer inspecting an installed dependency should start at:

node_modules/@wibus/cuelens/dist/docs/README.md

The complete Usage guide has one source owner in docs/usage.md; this README is only the package entry point and quick start.

Playground

The playground has its own package manifest and lockfile, so this repository is not a monorepo.

cd playground
pnpm install
pnpm dev

Open http://127.0.0.1:4173/. Guided mode exercises host-owned steps and interaction triggers alongside independent product UI. Timeline mode exercises the automatic runtime, and Studio combines CodeMirror JSON with visual tracks, keyframes, beats, shots, cues, validation, and live preview.

Verify a change

pnpm install
pnpm check
pnpm pack

pnpm build emits ESM, declarations, source maps, and public documentation at dist/docs/. Historical execution plans remain repository-only. pnpm pack runs that build again and creates the same file set npm will publish.

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. Maintainers should follow RELEASING.md instead of publishing directly from a workstation.