@octanejs/embla-carousel 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) David Jerleke.
+
+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,38 @@
+# @octanejs/embla-carousel
+
+Octane binding for `embla-carousel-react@8.6.0`. It keeps the familiar default
+`useEmblaCarousel` API while reusing Embla's framework-neutral runtime.
+
+```tsrx
+import useEmblaCarousel from '@octanejs/embla-carousel';
+
+export function Carousel() @{
+	const [viewportRef, api] = useEmblaCarousel({ loop: true });
+
+	<section>
+		<div ref={viewportRef}>
+			<div>
+				<div>First</div>
+				<div>Second</div>
+			</div>
+		</div>
+		<button onClick={() => api?.scrollPrev()}>Previous</button>
+		<button onClick={() => api?.scrollNext()}>Next</button>
+	</section>
+}
+```
+
+Replace the React import:
+
+```diff
+- import useEmblaCarousel from 'embla-carousel-react';
++ import useEmblaCarousel from '@octanejs/embla-carousel';
+```
+
+The call signature, tuple result, exported types, and `globalOptions` property
+match upstream. The published package has no React runtime or type dependency.
+
+Lifecycle and option updates run against the pinned React adapter as a live
+differential oracle. Real layout and pointer physics are delegated unchanged to
+`embla-carousel`. The required Chromium lane verifies nonzero layout, scrolling,
+selection updates, and destroy cleanup against the real core.

package/UPSTREAM.md

@@ -0,0 +1,58 @@
+# Upstream Embla Carousel React audit
+
+This port targets the immutable `embla-carousel-react@8.6.0` release.
+
+- Repository: `https://github.com/davidjerleke/embla-carousel`
+- Tag commit: `0fe65834136f1aa35e4c1a4a477e5ccb4bb5ee54`
+- npm integrity: `sha512-0/PjqU7geVmo6F734pmPqpyHqiM99olvyecY7zdweCw+6tKEXnrE90pBiBbMMU8s5tICemzpQ3hi5EpxzGW+JA==`
+- Runtime/core oracle: `embla-carousel@8.6.0`
+- Reactive utility oracle: `embla-carousel-reactive-utils@8.6.0`
+- React oracle: `react@19.2.7` / `react-dom@19.2.7` (exact; required differential lane)
+- React types: `@types/react@19.2.17` (exact; declaration consumer matrix)
+- Advertised compatibility: exactly the 8.6.0 React adapter surface
+
+The MIT-licensed tag supplied the byte-exact files in `upstream/`. The npm
+artifact supplied the declaration and bundle check; it contains no source or
+tests. Vendored evidence is excluded from the published `files` list.
+
+## Export crosswalk
+
+| Upstream root export | Octane disposition | Evidence |
+| --- | --- | --- |
+| `default` (`useEmblaCarousel`) | Ported with `octane` hooks | `tests/conformance/binding.test.ts` |
+| `UseEmblaCarouselType` | Ported without semantic change | `typetests/public.test-d.ts` |
+| `EmblaViewportRefType` | Ported without semantic change | `typetests/public.test-d.ts` |
+| `./package.json` | Package metadata export | package pack check |
+
+## Source and test disposition
+
+| Upstream artifact | Disposition |
+| --- | --- |
+| `embla-carousel-react/src/index.ts` | Mirrored by `src/index.ts` |
+| `embla-carousel-react/src/components/useEmblaCarousel.ts` | Ported module-by-module; only the framework hook import and formatting differ |
+| `embla-carousel-reactive-utils/src/components/utils.ts` | Reused unchanged from the published framework-neutral dependency |
+| `embla-carousel-reactive-utils/src/index.ts` | Reused unchanged from the published framework-neutral dependency |
+| `embla-carousel-reactive-utils/src/__tests__/utils.test.ts` | Upstream suite registered as the `embla-pristine-utils` parity lane (`embla-carousel-pristine-utils`) |
+| React adapter tests | No test files exist at the pinned tag; `package.json`'s test script reports no tests |
+| Upstream type tests | None exist at the pinned tag; pristine declaration consumption and adapted public types are checked locally |
+
+## Differences
+
+There are no consumer-visible API divergences. Octane compiles the hook calls
+to stable call-site slots and uses native callback refs; neither changes the
+published tuple contract.
+
+Real pointer physics and layout remain owned by the unchanged Embla core. The
+adapter suite uses a controlled constructor boundary because jsdom has no
+layout. An unpaired Octane browser harness under `tests/browser` opts into
+`testExecution.group: heavy-browser` and runs in Chromium via the generic
+heavy-browser discovery lane. It verifies nonzero layout, scrolling, selection
+updates, and destroy cleanup. Browser behavior is not simulated with jsdom
+geometry mocks.
+
+Every port-authored runtime test and repo-authored type probe is classified in
+`audit/test-classifications.json`. Unpaired conformance/browser/hydration/SSR
+cases stay Octane-only and outside React-parity ownership. The required
+pristine/adapted type probes are `repo-authored-type-oracle` evidence paired
+with the type-parity lanes; the required differential lane is the React runtime
+oracle and rejects React/ReactDOM version drift from the pins above.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@octanejs/embla-carousel",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "description": "Embla Carousel bindings for Octane, API-compatible with embla-carousel-react 8.6.0.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/embla-carousel"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "UPSTREAM.md",
+    "status.json"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "embla-carousel": "8.6.0",
+    "embla-carousel-reactive-utils": "8.6.0"
+  },
+  "peerDependencies": {
+    "octane": "0.1.35"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.17",
+    "embla-carousel-react": "8.6.0",
+    "playwright": "^1.61.1",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10",
+    "@octanejs/testing-library": "0.1.32",
+    "octane": "0.1.35"
+  },
+  "scripts": {
+    "test": "node audit/type-parity.mjs && vitest run --root ../.. --project embla-carousel --project embla-carousel-pristine-utils --project embla-carousel-differential --project embla-carousel-hydration --project embla-carousel-ssr --project embla-carousel-audit --project embla-carousel-browser",
+    "typecheck": "tsrx-tsc --noEmit -p tsconfig.json && tsc --noEmit -p typetests/pristine.tsconfig.json && tsrx-tsc --noEmit -p typetests/tsconfig.json"
+  }
+}

package/src/components/useEmblaCarousel.ts

@@ -0,0 +1,66 @@
+import { useCallback, useEffect, useRef, useState } from 'octane';
+import { areOptionsEqual, arePluginsEqual, canUseDOM } from 'embla-carousel-reactive-utils';
+import EmblaCarousel, {
+	type EmblaCarouselType,
+	type EmblaOptionsType,
+	type EmblaPluginType,
+} from 'embla-carousel';
+
+export type EmblaViewportRefType = <ViewportElement extends HTMLElement>(
+	instance: ViewportElement | null,
+) => void;
+
+export type UseEmblaCarouselType = [EmblaViewportRefType, EmblaCarouselType | undefined];
+
+function useEmblaCarousel(
+	options?: EmblaOptionsType,
+	plugins?: EmblaPluginType[],
+): UseEmblaCarouselType;
+function useEmblaCarousel(
+	...args: [options?: EmblaOptionsType, plugins?: EmblaPluginType[], slot?: symbol]
+): UseEmblaCarouselType {
+	const hasCompilerSlot = typeof args.at(-1) === 'symbol';
+	const options = (hasCompilerSlot && args.length === 1 ? undefined : args[0]) ?? {};
+	const plugins = (hasCompilerSlot && args.length === 2 ? undefined : args[1]) ?? [];
+	const storedOptions = useRef(options);
+	const storedPlugins = useRef(plugins);
+	const [emblaApi, setEmblaApi] = useState<EmblaCarouselType>();
+	const [viewport, setViewport] = useState<HTMLElement>();
+
+	const reInit = useCallback(() => {
+		if (emblaApi) emblaApi.reInit(storedOptions.current, storedPlugins.current);
+	}, [emblaApi]);
+
+	useEffect(() => {
+		if (areOptionsEqual(storedOptions.current, options)) return;
+		storedOptions.current = options;
+		reInit();
+	}, [options, reInit]);
+
+	useEffect(() => {
+		if (arePluginsEqual(storedPlugins.current, plugins)) return;
+		storedPlugins.current = plugins;
+		reInit();
+	}, [plugins, reInit]);
+
+	useEffect(() => {
+		if (canUseDOM() && viewport) {
+			EmblaCarousel.globalOptions = useEmblaCarousel.globalOptions;
+			const newEmblaApi = EmblaCarousel(viewport, storedOptions.current, storedPlugins.current);
+			setEmblaApi(newEmblaApi);
+			return () => newEmblaApi.destroy();
+		}
+
+		setEmblaApi(undefined);
+	}, [viewport, setEmblaApi]);
+
+	return [setViewport as EmblaViewportRefType, emblaApi];
+}
+
+declare namespace useEmblaCarousel {
+	let globalOptions: EmblaOptionsType | undefined;
+}
+
+useEmblaCarousel.globalOptions = undefined;
+
+export default useEmblaCarousel;

package/src/index.ts

@@ -0,0 +1,5 @@
+export {
+	type UseEmblaCarouselType,
+	type EmblaViewportRefType,
+	default,
+} from './components/useEmblaCarousel';

package/status.json

@@ -0,0 +1,14 @@
+{
+  "upstream": {
+    "package": "embla-carousel-react",
+    "version": "8.6.0",
+    "core": "embla-carousel@8.6.0"
+  },
+  "surface": "Complete package-root adapter: default useEmblaCarousel hook, its viewport-ref and tuple types, and globalOptions; the framework-neutral Embla core and reactive equality utilities are reused unchanged.",
+  "divergences": [],
+  "ssr": "The hook constructs no carousel without DOM globals; client attachment initializes the core.",
+  "verified": "2026-08-02",
+  "notes": [
+    "The live React differential covers adapter lifecycle. A required Chromium lane verifies real layout, scrolling, selection updates, and destroy cleanup."
+  ]
+}