@frame-by-frame/core 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mário Veronesi Medina
+
+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,123 @@
+# frame-by-frame
+
+[![CI](https://github.com/mariozenmedina/frame-by-frame/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mariozenmedina/frame-by-frame/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A framework-agnostic TypeScript engine for mapping scroll position to video time.
+
+> [!IMPORTANT]
+> `frame-by-frame` `1.0.0-rc.1` is a release candidate for integration feedback, not a stable production release. Compatibility evidence remains qualified by the tested browsers, operating systems, codecs, and media environments.
+
+## Why frame-by-frame?
+
+Scroll-driven video experiences repeatedly need the same careful behavior: deterministic timeline mapping, bounded media seeks, responsive assets, loading coordination, and complete cleanup. `frame-by-frame` provides those responsibilities as a small engine with an explicit lifecycle instead of coupling them to an application or frontend framework.
+
+- Map pixel or normalized scroll ranges to forward or reverse media-time ranges.
+- Use multiple clips and global or per-segment easing in one timeline.
+- Drive independent horizontal and vertical targets from one controller.
+- Choose native video by default or opt into a video-backed 2D canvas.
+- Coordinate immediate, full-file, manual, viewport, and first-use loading.
+- Respect reduced-motion preferences and apply ordered responsive overrides.
+- Keep imports SSR-safe and release every owned resource with `destroy()`.
+
+Native scrolling is never intercepted. The engine coalesces scroll work with animation frames and keeps only the latest pending seek.
+
+## Quick start
+
+Install the release-candidate channel with one package manager:
+
+```sh
+pnpm add @frame-by-frame/core@next
+# or
+npm install @frame-by-frame/core@next
+```
+
+The root entry is the recommended video-only API:
+
+```ts
+import { createFrameByFrame } from '@frame-by-frame/core';
+
+const controller = createFrameByFrame({
+  axes: {
+    y: {
+      bindings: [
+        {
+          id: 'story',
+          target: '#story-video',
+          clips: [
+            {
+              id: 'intro',
+              sources: [
+                { src: '/media/intro.webm', type: 'video/webm' },
+                { src: '/media/intro.mp4', type: 'video/mp4' },
+              ],
+            },
+          ],
+          easing: 'ease-in-out',
+          segments: [
+            {
+              scroll: [0, 1],
+              scrollUnit: 'progress',
+              clip: 'intro',
+              media: [0, 8],
+            },
+          ],
+        },
+      ],
+    },
+  },
+});
+
+await controller.mount();
+await controller.whenReady();
+
+// On application teardown:
+controller.destroy();
+```
+
+`mount()` resolves DOM ownership and starts configured automatic loading without waiting for the network. `whenReady()` is the aggregate readiness barrier for application loading screens.
+
+## Package entries
+
+| Entry                         | Purpose                                                        |
+| ----------------------------- | -------------------------------------------------------------- |
+| `@frame-by-frame/core`        | Recommended video-only controller, timeline, errors, and types |
+| `@frame-by-frame/core/video`  | Explicit alias for the same video-only API                     |
+| `@frame-by-frame/core/canvas` | Opt-in factory supporting video and canvas bindings            |
+| `@frame-by-frame/core/types`  | Runtime-empty, type-only entry                                 |
+
+## Documentation
+
+Start with the [documentation map](docs/README.md), then choose the path that matches your task:
+
+- [Recipes](docs/recipes/README.md) for axes, multi-clip timelines, loading, canvas, responsive behavior, and framework lifecycles.
+- [Guides](docs/guides/README.md) for media preparation, performance, accessibility, and browser support.
+- [API reference](docs/api/controller.md) for controller behavior, with dedicated [timeline](docs/api/timeline.md), [video](docs/api/video.md), and [canvas](docs/api/canvas.md) references.
+- [Troubleshooting](docs/troubleshooting.md) for common integration symptoms and stable error codes.
+- [Version 1 acceptance matrix](docs/v1-acceptance.md) for implemented, operator-pending, and release-pending evidence.
+- [Changelog](CHANGELOG.md) and the [release maintainer guide](docs/guides/releasing.md) for version history and the publication boundary.
+- [Release candidate notes](docs/releases/v1.0.0-rc.1.md) for installation, compatibility evidence, and known limitations in `1.0.0-rc.1`.
+- [Architecture decisions](docs/decisions/0001-package-foundation.md) for the public design rationale.
+
+## Development
+
+Use Node.js 24 LTS and pnpm 11. CI also validates the supported Node.js 22 line.
+
+```sh
+pnpm install
+pnpm check
+```
+
+The required gate covers formatting, documentation links, linting, TypeScript, deterministic tests and coverage, builds, bundle budgets, package metadata, declarations, and built entry imports. The prepared [browser validation suite](docs/guides/browser-support.md) is run separately by an operator because codecs and media presentation vary by runtime.
+
+## Contributing
+
+Focused bug reports, documentation improvements, design feedback, and implementation proposals are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request. Significant API or architecture changes should begin with an issue so their trade-offs can be discussed publicly.
+
+The core remains framework agnostic. A maintained Vue example is planned after the first core release; other framework examples will be open to community pull requests once that example contract is established.
+
+Project communication, code, tests, and public documentation are in English. See the [Code of Conduct](CODE_OF_CONDUCT.md), [support policy](SUPPORT.md), [security policy](SECURITY.md), and [governance model](GOVERNANCE.md).
+
+## License
+
+Licensed under the [MIT License](LICENSE).

package/dist/canvas.d.ts

@@ -0,0 +1,8 @@
+import { $ as Timeline, A as FrameByFrameBreakpointOverride, B as FrameByFrameOptions, C as FrameByFrameBindingBaseConfig, D as FrameByFrameBindingState, E as FrameByFrameBindingOverride, F as FrameByFrameErrorOptions, G as FrameByFrameUpdateReason, H as FrameByFrameState, I as FrameByFrameEventMap, J as ReducedMotionBehavior, K as FrameConfig, L as FrameByFrameFrameEvent, M as FrameByFrameErrorCode, N as FrameByFrameErrorDetails, O as FrameByFrameBreakpointChangeEvent, P as FrameByFrameErrorInfo, Q as ScrollUnit, R as FrameByFrameLoadProgressEvent, S as FrameByFrameAxisState, T as FrameByFrameBindingEvent, U as FrameByFrameStatus, V as FrameByFrameSeekRequestEvent, W as FrameByFrameUpdateEvent, X as ScrollSource, Y as RendererType, Z as ScrollSourceReference, _ as EasingName, a as CanvasFrameByFrameAxisConfig, at as VideoLoadProgress, b as FrameByFrameAxisConfig, c as CanvasFrameByFrameBindingOverride, ct as VideoLoadingTrigger, d as CanvasFrameByFrameController, dt as VideoSeekConfig, et as TimelineOptions, f as CanvasFrameByFrameOptions, ft as VideoSourceConfig, g as EasingFunction, h as Easing, i as CanvasFrameByFrameAxesConfig, it as VideoClipConfig, j as FrameByFrameController, k as FrameByFrameBreakpointConfig, l as CanvasFrameByFrameBreakpointConfig, lt as VideoPreload, m as CanvasRendererOverride, n as CanvasBindingConfig, nt as TimelineResolution, o as CanvasFrameByFrameAxisOverride, ot as VideoLoadState, p as CanvasRendererConfig, q as MediaCrossOrigin, r as CanvasFit, rt as TimelineSegment, s as CanvasFrameByFrameBindingConfig, st as VideoLoadingConfig, t as AxisName, tt as TimelinePhase, u as CanvasFrameByFrameBreakpointOverride, ut as VideoRendererConfig, v as ElementReference, w as FrameByFrameBindingConfig, x as FrameByFrameAxisOverride, y as FrameByFrameAxesConfig, z as FrameByFrameLoadedMetadataEvent } from "./types-BYfMRnsj.js";
+import { n as FrameByFrameError, t as createTimeline } from "./timeline-DDuRBPRJ.js";
+//#region src/canvas.d.ts
+/** Creates an SSR-safe controller with opt-in native-video and 2D-canvas renderers. */
+declare const createFrameByFrame: (options: CanvasFrameByFrameOptions) => CanvasFrameByFrameController;
+//#endregion
+export { type AxisName, type CanvasBindingConfig, type CanvasFit, type CanvasFrameByFrameAxesConfig, type CanvasFrameByFrameAxisConfig, type CanvasFrameByFrameAxisOverride, type CanvasFrameByFrameBindingConfig, type CanvasFrameByFrameBindingOverride, type CanvasFrameByFrameBreakpointConfig, type CanvasFrameByFrameBreakpointOverride, type CanvasFrameByFrameController, type CanvasFrameByFrameOptions, type CanvasRendererConfig, type CanvasRendererOverride, type Easing, type EasingFunction, type EasingName, type ElementReference, type FrameByFrameAxesConfig, type FrameByFrameAxisConfig, type FrameByFrameAxisOverride, type FrameByFrameAxisState, type FrameByFrameBindingBaseConfig, type FrameByFrameBindingConfig, type FrameByFrameBindingEvent, type FrameByFrameBindingOverride, type FrameByFrameBindingState, type FrameByFrameBreakpointChangeEvent, type FrameByFrameBreakpointConfig, type FrameByFrameBreakpointOverride, type FrameByFrameController, FrameByFrameError, type FrameByFrameErrorCode, type FrameByFrameErrorDetails, type FrameByFrameErrorInfo, type FrameByFrameErrorOptions, type FrameByFrameEventMap, type FrameByFrameFrameEvent, type FrameByFrameLoadProgressEvent, type FrameByFrameLoadedMetadataEvent, type FrameByFrameOptions, type FrameByFrameSeekRequestEvent, type FrameByFrameState, type FrameByFrameStatus, type FrameByFrameUpdateEvent, type FrameByFrameUpdateReason, type FrameConfig, type MediaCrossOrigin, type ReducedMotionBehavior, type RendererType, type ScrollSource, type ScrollSourceReference, type ScrollUnit, type Timeline, type TimelineOptions, type TimelinePhase, type TimelineResolution, type TimelineSegment, type VideoClipConfig, type VideoLoadProgress, type VideoLoadState, type VideoLoadingConfig, type VideoLoadingTrigger, type VideoPreload, type VideoRendererConfig, type VideoSeekConfig, type VideoSourceConfig, createFrameByFrame, createTimeline };
+//# sourceMappingURL=canvas.d.ts.map

package/dist/canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.d.ts","names":[],"sources":["../src/canvas.ts"],"mappings":";;;;cAyCa,qBACX,SAAS,8BACR"}