open-index/open-npm huggingface dataset:
npm package: @immersive-scroll/cli
Description: CLI for immersive scroll frame extraction and validation.
Latest version: 0.1.0

# immersive-scroll

CLI for preparing and validating immersive scroll assets. This package turns source video into deterministic frame folders and manifests that the runtime packages can consume directly.

## Install

```bash
pnpm add immersive-scroll
```

Or run it without adding it to your app:

```bash
npx immersive-scroll --help
```

Inside this monorepo, the simplest example-asset workflow is:

```bash
pnpm extract "<video-path>"
```

That wrapper rebuilds every example app's shared `/public/immersive/scene` folder automatically.

## Commands

- `extract <video> <output-folder>`: extract frames, write a manifest, and generate a frame index.
- `validate <frames-folder>`: validate an existing frame directory and return a machine-readable report.
- `repair <video> <frames-folder>`: regenerate frames for a broken or incomplete folder.
- `manifest <frames-folder>`: print the resolved manifest JSON for a folder.
- `hash <video>`: print the content hash for a source video.
- `doctor`: print Node, platform, temp directory, and `ffmpeg` availability details.

## Examples

```bash
immersive-scroll extract ./assets/story.mp4 ./public/immersive/story --clean
immersive-scroll extract ./assets/story.mp4 ./public/immersive/story --max-frames 180 --clean
immersive-scroll validate ./public/immersive/story
immersive-scroll doctor
```

## Notes

- `ffmpeg-static` is bundled, so the default flow does not require a separately installed system `ffmpeg`.
- Extraction now defaults to roughly `250` frames, auto-lowers fps for long videos, scales oversized footage to landing-page dimensions, and tunes WebP quality automatically.
- The CLI writes manifests that match the contracts exported by `@immersive-scroll/shared`.
- The package is designed for build pipelines and local authoring tools, not browser usage.
npm package: @immersive-scroll/core
Description: Framework-agnostic immersive scroll engine.
Latest version: 0.1.0

# @immersive-scroll/core

Framework-agnostic immersive engine primitives. Use this package when you need the scene lifecycle, frame manifest handling, progress math, and plugin hooks without committing to a specific UI framework.

## Install

```bash
pnpm add @immersive-scroll/core
```

## What it exports

- `createImmersiveEngine()`: create the headless engine instance.
- `normalizeImmersiveConfig()` and `mergeImmersiveConfig()`: resolve partial config safely.
- `createFrameStore()` and `createScrollStore()`: low-level state stores.
- `validateFrameManifest()` and `validateFrameDirectoryContract()`: manifest and asset integrity helpers.
- Shared types and utilities re-exported from `@immersive-scroll/shared`.

## Minimal example

```ts
import { createImmersiveEngine } from '@immersive-scroll/core';

const engine = createImmersiveEngine({
  config: {
    framesPath: '/immersive/story',
    scrollbar: { enabled: true }
  },
  container: document.querySelector('#scene'),
  targets: {
    canvas: document.querySelector('canvas')
  }
});

await engine.init();
await engine.updateProgress(0.35);
```

## Use this package when

- you are building a custom adapter or wrapper,
- you need plugin or renderer control outside the packaged UI layers,
- or you want runtime logic on the server or in tooling without React, Solid, or custom elements.
npm package: @immersive-scroll/next
Description: Next.js adapter for immersive scroll video.
Latest version: 0.1.0

# @immersive-scroll/next

Client-only wrappers for using immersive scroll inside Next.js applications. This package keeps the integration surface explicit for App Router projects while reusing the React adapter underneath.

## Install

```bash
pnpm add @immersive-scroll/next
```

## Exports

- `NextImmersiveScroll`: client-only alias of the React `ImmersiveScroll` component.
- `NextImmersiveProvider`: client-only alias of the React provider.
- `createImmersiveDynamicComponent()`: helper for dynamic client-only loading.
- `ensureClient()` and `withImmersiveClientOnly()`: guards for client boundaries.

## Quick start

```tsx
'use client';

import { NextImmersiveScroll } from '@immersive-scroll/next';

export default function ProductHero() {
  return (
    <NextImmersiveScroll framesPath="/immersive/hero">
      <section>Story content</section>
    </NextImmersiveScroll>
  );
}
```

## Notes

- Use this package for Next-specific boundaries. For component APIs and hooks, the underlying source of truth is still `@immersive-scroll/react`.
- The package is intended for client components and client-only wrappers, not server rendering.
npm package: @immersive-scroll/react
Description: React adapter for immersive scroll video.
Latest version: 0.1.0

# @immersive-scroll/react

React adapter for immersive scroll scenes. It bundles the provider, viewport/canvas composition, hooks, scrollbar, debug panel, and helper components needed to build scroll-driven storytelling UIs in React.

## Install

```bash
pnpm add @immersive-scroll/react
```

## Main exports

- `ImmersiveScroll`: root component that pins the viewport and drives the engine.
- `ImmersiveLayer`: overlay layer for HUDs, gradients, controls, and floating chrome.
- `ImmersiveFloating`, `ImmersiveTriggerZone`, `ImmersiveScrollbar`, `ImmersiveDebugPanel`
- Hooks including `useImmersiveFrame()`, `useImmersiveProgress()`, `useImmersiveScroll()`, and `useImmersiveScrollbar()`

## Quick start

```tsx
import {
  ImmersiveLayer,
  ImmersiveScroll,
  useImmersiveProgress
} from '@immersive-scroll/react';

function ProgressBadge() {
  const { progress } = useImmersiveProgress();
  return <span>Progress {Math.round(progress * 100)}%</span>;
}

export function StoryScene() {
  return (
    <ImmersiveScroll
      framesPath="/immersive/story"
      config={{ scrollbar: { enabled: true, visibilityMode: 'manual' } }}
      overlay={
        <ImmersiveLayer>
          <ProgressBadge />
        </ImmersiveLayer>
      }
    >
      <section>Story content</section>
    </ImmersiveScroll>
  );
}
```

## Notes

- The component tree is client-side and expects a public frame folder or explicit manifest path.
- Scrollbar placement and interactivity can be controlled through config or `scrollbarProps`.
- For Next.js-specific client wrappers, use `@immersive-scroll/next`.
npm package: @immersive-scroll/shared
Description: Shared contracts and utilities for immersive scroll.
Latest version: 0.1.0

# @immersive-scroll/shared

Shared contracts, constants, validators, and tiny utilities used by every package in the workspace. This is the lowest-level package and the right place for types and validation logic that must stay framework-neutral.

## Install

```bash
pnpm add @immersive-scroll/shared
```

## What it exports

- config types such as `ImmersiveConfig`, `PartialImmersiveConfig`, and `ScrollbarConfig`
- frame and manifest contracts including `ImmersiveFrameManifest`
- default config constants
- validators for config, manifest, and paths
- small utilities like `clamp()`, `deepMerge()`, `normalizePath()`, and `toError()`

## Example

```ts
import {
  DEFAULT_IMMERSIVE_CONFIG,
  type ImmersiveFrameManifest,
  validateFrameManifest
} from '@immersive-scroll/shared';
```

## Use this package when

- you are authoring adapters or tooling around immersive manifests,
- you need shared types in app code,
- or you want validation without importing the runtime engine.
npm package: @immersive-scroll/solid
Description: Solid adapter for immersive scroll video.
Latest version: 0.1.0

# @immersive-scroll/solid

Solid adapter for immersive scroll scenes. It exposes Solid-friendly components and hooks while reusing the shared contracts and core runtime.

## Install

```bash
pnpm add @immersive-scroll/solid
```

## Main exports

- `ImmersiveScroll`
- `ImmersiveCanvas`
- `ImmersiveLayer`
- `ImmersiveFloating`
- `ImmersiveScrollbar`
- `ImmersiveTriggerZone`
- hooks for frame, progress, scroll, config, and triggers

## Quick start

```tsx
import { ImmersiveScroll } from '@immersive-scroll/solid';

export function StoryScene() {
  return (
    <ImmersiveScroll framesPath="/immersive/story">
      <section>Story content</section>
    </ImmersiveScroll>
  );
}
```

## Notes

- The Solid package mirrors the shared immersive concepts, but the React package remains the most feature-complete adapter in this workspace.
- Use this adapter when Solid owns the route shell and you want the same manifest and scroll model as the React implementation.
npm package: @immersive-scroll/web
Description: Vanilla web adapter for immersive scroll video.
Latest version: 0.1.0

# @immersive-scroll/web

Framework-free DOM API and custom-element wrapper for immersive scroll scenes. Use this package when you need a runtime that can be mounted imperatively or dropped into a CMS or non-framework shell.

## Install

```bash
pnpm add @immersive-scroll/web
```

## Main exports

- `createImmersiveInstance()`: mount an immersive scene into an existing container.
- `destroyImmersiveInstance()`: dispose a mounted instance explicitly.
- `registerImmersiveCustomElement()`: register `<immersive-scroll>`.
- `ImmersiveScrollElement`: the custom-element implementation.

## Imperative example

```ts
import { createImmersiveInstance } from '@immersive-scroll/web';

const container = document.querySelector('#scene');

if (container instanceof HTMLElement) {
  createImmersiveInstance({
    container,
    framesPath: '/immersive/story'
  });
}
```

## Custom element example

```ts
import { registerImmersiveCustomElement } from '@immersive-scroll/web';

registerImmersiveCustomElement();
```

```html
<immersive-scroll frames-path="/immersive/story"></immersive-scroll>
```