zumly 0.18.1 → 0.92.0

package/README.md

@@ -1,26 +1,46 @@
 <p align="center">
-  <a href="https://zumly.org">
-    <img src="https://raw.githubusercontent.com/zumly/website/gh-pages/images/logo-zumly.png" width="200">
+  <a href="https://github.com/zumerlab/zumly">
+    <!-- Built from docs/zumly-logo.png in this repo; raw URL so the image works on npm too -->
+    <img src="https://raw.githubusercontent.com/zumerlab/zumly/main/docs/zumly-logo.png" alt="Zumly" width="200">
   </a>
 </p>
 
+<h1 align="center">Z over XY</h1>
+
+<p align="center"><strong>Focus-driven navigation.</strong></p>
+<p align="center"><strong>Zoom into what matters.</strong></p>
+
 <p align="center">
-  Zumly is a JavaScript library for building zooming user interfaces. Create zooming experiences using web standards.
+  <a href="https://www.npmjs.com/package/zumly"><img src="https://img.shields.io/npm/v/zumly.svg" alt="npm version"></a>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/zumly"><img src="https://img.shields.io/npm/v/zumly.svg"></a>
+  <strong>Zumly</strong> is a JavaScript library for <strong>hierarchical zoom navigation</strong>: you move in <strong>Z</strong> (depth) through discrete views laid out in the <strong>XY</strong> plane, with spatial transitions instead of flat screen swaps. It is inspired by <a href="https://en.wikipedia.org/wiki/Zooming_user_interface">zoomable user interfaces (ZUI)</a> but targets <strong>structured, trigger-driven</strong> zoom—not infinite pan/zoom canvases.
 </p>
 
 ## Status
 
-Zumly is under active development. The library is usable in production with a stable core API; view preloading, prefetch on hover, and multiple view sources (HTML, URL, async functions, web components) are supported. See [docs/roadMap.md](docs/roadMap.md) for improvement topics and roadmap.
+Zumly is under active development. The core stack is stable: depth and lateral navigation, pluggable transition drivers (CSS, WAAPI, none, Anime.js, GSAP, Motion, custom), unified nav UI (depth + lateral, eight positions), view resolver and prefetch cache, optional **plugin** API (<code>.use()</code>), and the **hash router** plugin. View sources include HTML strings, URLs, async functions, objects with <code>render()</code>, DOM nodes, and web component tags.
+
+Zoom-out geometry uses batched DOM reads plus pure math where possible to cut layout thrash before animations (see [Geometry optimization](docs/geometry-optimization.md)).
+
+**Docs:** [Roadmap & topics](docs/roadMap.md) · [Transition drivers](docs/DRIVER_API.md) · [Geometry notes](docs/geometry-optimization.md)
 
 ## Overview
 
-Zumly is a frontend library for creating **zoomable user interfaces** ([ZUI](https://en.wikipedia.org/wiki/Zooming_user_interface)). Instead of hyperlinks and windows, Zumly uses zooming as the main way to move through information: an infinite virtual canvas where you zoom into elements to reveal more detail.
+Unlike free-pan ZUIs, Zumly focuses on **discrete, hierarchical navigation**: users zoom into a focused element (<code>.zoom-me</code>) to open the next view, so **attention** (focus) and **depth** (Z) stay aligned with **layout** (XY).
+
+The engine is **UI-agnostic**—you supply markup and CSS. Transforms and timing are handled for you; design systems and frameworks integrate by resolving each view to a DOM subtree (see **View sources** and **Framework integration** below).
 
-The library focuses on **zoom transitions** and stays **UI-agnostic**—you bring your own CSS and layout. Any design system or custom styling works with Zumly.
+## What Zumly is
+
+Zumly is **not** a freeform zooming canvas or map-like navigation system. It is a **discrete, hierarchical zoom interface**: screens are **views** at different depths, connected by **triggers**, with continuous motion between them.
+
+It fits especially well when:
+
+* you want **focus-driven** flow (zoom into what matters)
+* **spatial context** between parent and child should persist
+* you are building menus, stories, dashboards, or exploratory UIs without a classic router-only metaphor
 
 ## Installation
 
@@ -93,7 +113,7 @@ const app = new Zumly({
 await app.init();
 ```
 
-- Live example: [CodePen](https://codepen.io/zumly/pen/gOPQovd)
+- Live example: [CodePen](https://codepen.io/zircle/pen/yyaXvRN)
 
 ### Options
 
@@ -105,33 +125,43 @@ await app.init();
 | `initialView` | string | Yes | Name of the first view to show. |
 | `views` | object | Yes | Map of view names to view sources (see View sources below). |
 | `preload` | string[] | No | View names to resolve and cache when the app initializes. |
-| `transitions` | object | No | Duration, ease, cover, and effects for zoom transitions. |
+| `transitions` | object | No | Duration, ease, cover, driver, effects, stagger, hideTrigger for zoom transitions. |
+| `deferred` | boolean | No | Defer content rendering until after animation completes (default: `false`). |
 | `debug` | boolean | No | Enable debug messages (default: `false`). |
+| `lateralNav` | boolean \| object | No | Lateral navigation UI: `{ mode, arrows, dots, keepAlive }`. |
+| `depthNav` | boolean \| object | No | Depth navigation UI: `{ button, indicator }`. |
+| `navPosition` | string | No | Nav bar position preset (default: `'bottom-center'`). |
+| `inputs` | boolean \| object | No | Input methods: `{ click, keyboard, wheel, touch }`. |
 | `componentContext` | object | No | Context passed to component-style views. |
 
 **Transitions (optional):**
 
 ```js
 transitions: {
-  driver: 'css',   // 'css' | 'waapi' | 'anime' | 'gsap' | 'motion' | 'none' or custom function(spec, onComplete)
-  effects: ['blur', 'sepia', 'saturate'],  // background view effects
-  cover: 'width',   // or 'height' — how the previous view scales to cover the trigger
+  driver: 'css',       // 'css' | 'waapi' | 'anime' | 'gsap' | 'motion' | 'none' or custom function(spec, onComplete)
+  cover: 'width',      // or 'height' — how the previous view scales to cover the trigger
   duration: '1s',
   ease: 'ease-in-out',
+  effects: ['blur(3px) brightness(0.7)', 'blur(8px) saturate(0)'],  // CSS filters for [previous, last] background views
+  stagger: 0,          // delay (ms) between layers during transition
+  hideTrigger: false,  // false | true (visibility:hidden) | 'fade' (opacity crossfade)
+  // threshold: { enabled: true, duration: 300, commitAt: 0.5 }  // parsed but not wired in the engine yet
 }
 ```
 
-**Transition drivers:** Zoom animations are handled by a pluggable driver so you can swap the implementation without changing app logic.
+`transitions.parallax` is accepted for compatibility but **not applied** (reserved; intensity is fixed to `0` in the engine).
+
+**Transition drivers:** Zoom animations are handled by a pluggable driver (`transitions.driver`). You can swap implementations without changing app logic. To author your own, see [docs/DRIVER_API.md](docs/DRIVER_API.md) and the `zumly/driver-helpers` export.
 
 | Driver | Description |
 |--------|-------------|
 | `'css'` (default) | CSS keyframes and `animationend`; uses `zumly.css` variables. |
-| `'waapi'` | Web Animations API (`element.animate()`). |
-| `'anime'` | [Anime.js](https://animejs.com/) — load the library (e.g. from CDN) before use. |
-| `'gsap'` | [GSAP](https://greensock.com/gsap/) — load the library (e.g. from CDN) before use. |
-| `'motion'` | [Motion](https://motion.dev/) (motion.dev) — load the library (e.g. from CDN) before use. |
+| `'waapi'` | Web Animations API (`element.animate()`). No extra dependency. |
 | `'none'` | No animation; applies final state immediately. Useful for tests or instant UX. |
-| `function(spec, onComplete)` | Custom driver. Receives a transition spec and must call `onComplete()` when done. |
+| `'anime'` | [Anime.js](https://animejs.com/) — requires global `anime` (load from CDN before use). |
+| `'gsap'` | [GSAP](https://greensock.com/gsap/) — requires global `gsap` (load from CDN before use). |
+| `'motion'` | [Motion](https://motion.dev/) — requires global `Motion` (load from CDN before use). |
+| `function(spec, onComplete)` | Custom driver. Receives `{ type, currentView, previousView, lastView, currentStage, duration, ease }` and must call `onComplete()` when done. |
 
 Example with instant transitions (e.g. for tests):
 
@@ -144,15 +174,67 @@ const app = new Zumly({
 });
 ```
 
+**Lateral navigation:**
+
+```js
+lateralNav: true                            // mode: 'auto' (default)
+lateralNav: false                           // disabled
+lateralNav: { mode: 'always' }              // always show when siblings exist
+lateralNav: { mode: 'auto', dots: false }   // auto mode, no dots
+```
+
+| Mode | Description |
+|------|-------------|
+| `'auto'` (default) | Shows lateral nav only when the current view doesn't cover the full canvas — preserving spatial context. |
+| `'always'` | Always shows lateral nav when siblings exist, regardless of coverage. |
+
+In `'auto'` mode, when a view covers 100% of the canvas the user perceives a new independent space, so the lateral nav is suppressed to avoid a floating control with no visual context.
+
+**Navigation position (`navPosition`):**
+
+```js
+navPosition: 'bottom-center'   // default
+```
+
+| Preset | Position | Layout |
+|--------|----------|--------|
+| `'bottom-center'` | Bottom center | Horizontal |
+| `'bottom-left'` | Bottom left | Horizontal |
+| `'bottom-right'` | Bottom right | Horizontal |
+| `'top-center'` | Top center | Horizontal |
+| `'top-left'` | Top left | Horizontal |
+| `'top-right'` | Top right | Horizontal |
+| `'middle-left'` | Left center | Vertical |
+| `'middle-right'` | Right center | Vertical |
+
+The `'middle-left'` and `'middle-right'` presets render the nav bar vertically with rotated arrows.
+
 **Zoomable elements:**
 
 - Give the view root the class `z-view`.
 - Add class `zoom-me` and `data-to="viewName"` to the element that triggers zoom-in.
-- Optional per-trigger: `data-with-duration`, `data-with-ease`.
+- Per-trigger overrides via `data-*` attributes:
+
+| Attribute | Description |
+|-----------|-------------|
+| `data-to` | **Required.** Target view name. |
+| `data-with-duration` | Override transition duration (e.g. `"2s"`). |
+| `data-with-ease` | Override easing function. |
+| `data-with-cover` | Override cover dimension (`"width"` or `"height"`). |
+| `data-with-stagger` | Override stagger delay in ms (e.g. `"100"`). |
+| `data-with-effects` | Override effects (pipe-separated: `"blur(5px)\|blur(10px)"`). |
+| `data-hide-trigger` | Override hideTrigger (`"fade"` or presence = hide). |
+| `data-deferred` | Override deferred rendering (presence = true). |
+| `data-*` | Any other data attribute becomes a prop in `ViewContext.props`. |
 
 ```html
 <div class="z-view">
-  <div class="zoom-me" data-to="detail" data-with-duration="2s" data-with-ease="ease-in">
+  <div class="zoom-me" data-to="detail"
+       data-with-duration="2s"
+       data-with-ease="ease-in"
+       data-with-cover="height"
+       data-with-stagger="100"
+       data-id="42">
     Zoom in
   </div>
 </div>
@@ -160,15 +242,147 @@ const app = new Zumly({
 
 ### View sources
 
-Views can be:
+Each entry in `views` is a **view source**. The resolver detects the type and resolves to a DOM node. Hyphenated view names (e.g. `'my-dashboard'`) are resolved as keys in `views` first; only raw template strings with a hyphen are treated as web components.
+
+| Type | Example | Cached? |
+|------|---------|---------|
+| **HTML string** | `'<div class="z-view">…</div>'` | Yes (indefinitely) |
+| **URL** | `'/views/detail.html'`, `https://…` | Yes (5 min TTL) |
+| **Async function** | `(ctx) => fetch(...).then(r => r.text())` or return `HTMLElement` | No |
+| **Object with `render()`** | `{ render(ctx) { return '<div>…</div>' }, mounted?() }` | No |
+| **Web component** | `'my-view'` (string with hyphen, not a key in `views`) | No |
+
+**View pipeline:** Resolve → normalize `.z-view` → insert into canvas → call `mounted()` (if present). Static/URL views are cloned from cache on each `get()` so consumers cannot mutate the stored node.
+
+### Framework integration
+
+Zumly is framework-agnostic. Since views resolve to DOM elements, any framework that can mount into a container works out of the box. Use **function views** or **object views** to bridge your framework:
+
+**React**
+
+```jsx
+import { createRoot } from 'react-dom/client'
+import Dashboard from './Dashboard'
+
+const app = new Zumly({
+  mount: '.canvas',
+  initialView: 'home',
+  views: {
+    home: '<div class="z-view"><div class="zoom-me" data-to="dashboard" data-id="42">Open</div></div>',
+    dashboard: ({ target, props }) => {
+      const root = createRoot(target)
+      root.render(<Dashboard id={props.id} />)
+    }
+  }
+})
+```
+
+**Vue**
+
+```js
+import { createApp } from 'vue'
+import Dashboard from './Dashboard.vue'
+
+views: {
+  dashboard: ({ target, props }) => {
+    createApp(Dashboard, { id: props.id }).mount(target)
+  }
+}
+```
+
+**Svelte**
+
+```js
+import Dashboard from './Dashboard.svelte'
+
+views: {
+  dashboard: ({ target, props }) => {
+    new Dashboard({ target, props: { id: props.id } })
+  }
+}
+```
+
+**Angular**
+
+```ts
+views: {
+  dashboard: ({ target, props }) => {
+    const compRef = viewContainerRef.createComponent(DashboardComponent)
+    compRef.instance.id = props.id
+    target.appendChild(compRef.location.nativeElement)
+  }
+}
+```
+
+**Key points:**
 
-- **HTML string** — static markup.
-- **Async function** — `(context) => string | Promise<string>` or return an `HTMLElement`.
-- **Object with `render()`** — `{ render(): string | Promise<string>, mounted?(): void }`.
-- **URL** — path or full URL to an HTML file (fetched and cached).
-- **Web component tag name** — string containing a hyphen (e.g. `'my-view'`); the custom element is created after it is defined.
+- The `target` parameter is a fresh `<div>` created by Zumly — mount your component there.
+- `props` contains data attributes from the trigger element (`data-id="42"` → `props.id`).
+- `componentContext` (constructor option) is passed as `context` to all function/object views — use it for shared state (router, store, API client).
+- Function views are **never cached** — they resolve fresh each time, so framework components get proper lifecycle management.
+- Use `mounted()` (object views) for post-insertion setup — it runs after the node is in the DOM.
+- Zumly handles wrapped elements (e.g. Svelte's extra parent div) in its cleanup logic.
 
-Preloading: use `preload: ['viewA', 'viewB']` to resolve those views on init. Hovering over a `zoom-me` trigger prefetches its target view; when a view becomes current, its `zoom-me` targets are prefetched in the background.
+### Preload and prefetch
+
+- **Eager preload:** `preload: ['viewA', 'viewB']` — those views are resolved and cached during `init()`.
+- **Hover prefetch:** `mouseover` on a `.zoom-me[data-to]` trigger prefetches its target in the background.
+- **Focus prefetch:** `focusin` on a `.zoom-me[data-to]` also prefetches (for keyboard/accessibility).
+- **Scan prefetch:** When a view becomes current, all `.zoom-me[data-to]` targets inside it are prefetched in the background. This works on touch devices where hover is unavailable.
+
+### Plugins
+
+Zumly has a lightweight plugin system. Register plugins with `.use()` before or after `init()`:
+
+```js
+app.use(plugin, options)
+```
+
+A plugin is an object with `install(instance, options)` or a plain function `(instance, options) => void`.
+
+#### Router plugin
+
+Syncs the browser URL hash with Zumly's navigation state. Browser back triggers zoom-out or lateral navigation. Forward is intentionally blocked — in a ZUI, zoom-in requires a trigger element for proper origin and animation context.
+
+```js
+// Script tag
+const app = new Zumly({ ... })
+app.use(Zumly.Router)
+await app.init()
+
+// ES Module (named export from the package entry)
+import { Zumly, ZumlyRouter } from 'zumly'
+const app = new Zumly({ ... })
+app.use(ZumlyRouter)
+await app.init()
+```
+
+The UMD/IIFE bundle attaches the same plugin as `Zumly.Router`. There is no separate published subpath for the router; import it from `'zumly'` or use `Zumly.Router` on `window` when using a script tag.
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `separator` | string | `'/'` | Character used to join view path segments in the hash. |
+| `prefix` | string | `'/'` | Prefix before the path in the hash. |
+
+**Behavior:**
+
+| Action | Hash update | History |
+|--------|-------------|---------|
+| Zoom in | `pushState` | Enables browser back |
+| Lateral | `pushState` | Enables browser back |
+| Zoom out | `replaceState` | No forward entry |
+| Browser back | Triggers `zoomOut()` or lateral `goTo()` | — |
+| Browser forward | Blocked (`history.back()`) | — |
+
+**Example URL:** `#/home/showcases/mercedes`
+
+### Limitations and non-goals
+
+- **No deep-linking:** The router plugin syncs hash on navigation and supports browser back, but does not support forward or deep-linking (entering a multi-level URL directly). In a ZUI, zoom-in requires a trigger element for proper spatial context.
+- **Resize handling:** Cheap correction when canvas resizes — translate and origin scaled by ratio; scale preserved. Correction is deferred if a transition is running.
+- **Remote views:** URL-backed views use `innerHTML`; sanitize external content to avoid XSS.
 
 ## Development
 
@@ -212,13 +426,21 @@ See [CHANGELOG.md](CHANGELOG.md) for version history.
 
 ## Roadmap
 
-- Additional view/template adapters
-- Lateral navigation (same zoom level)
-- Navigation widget and programmatic navigation
-- Router integration (e.g. URL sync)
-- Recalculate zoom on window resize
+**Done:**
+- Depth and lateral navigation (`zoomIn`, `zoomOut`, `goTo`, `back`, `zoomTo`)
+- Lateral nav UI (`lateralNav`: `mode` auto/always, arrows, dots, `keepAlive`)
+- Depth nav UI (`depthNav`) and `navPosition` presets
+- Inputs toggles (`inputs`: wheel, keyboard, click, touch)
+- Plugin system (`use()`), router plugin (hash sync, back, forward blocked)
+- Resize correction (translate/origin scaling; deferred while transitioning)
+- Pluggable drivers (CSS, WAAPI, none, Anime.js, GSAP, Motion, custom)
+- Batched zoom-out reads + math helpers to reduce reflow (see [geometry-optimization.md](docs/geometry-optimization.md))
+
+**Planned:**
+- Router deep-linking (open a multi-level hash cold)
+- Accessibility (focus moves, broader ARIA)
 
-Details and more topics: [docs/roadMap.md](docs/roadMap.md).
+Details and more topics: [docs/roadMap.md](docs/roadMap.md). Driver contract and helpers: [docs/DRIVER_API.md](docs/DRIVER_API.md).
 
 ## Community
 
@@ -226,7 +448,7 @@ Details and more topics: [docs/roadMap.md](docs/roadMap.md).
 
 ## Origin
 
-Zumly is a reimagined, framework-agnostic zoom engine inspired by [Zircle UI](https://github.com/zircleUI/zircleUI). It can be used together with [Orbit](https://github.com/zumerlab/orbit) for radial layouts.
+Zumly is a reimagined, framework-agnostic zoom engine inspired by [Zircle UI](https://github.com/zircleUI/zircleUI). Part of the [Zumerlab](https://github.com/zumerlab) ecosystem — use it with [Orbit](https://github.com/zumerlab/orbit) for radial layouts and [SnapDOM](https://github.com/zumerlab/snapdom) for lightweight DOM diffing.
 
 ## License
 

package/dist/zumly.css

@@ -27,26 +27,70 @@
   user-select: none;
 }
 .z-view {
-  will-change: transform, opacity;
   content-visibility: auto;
 }
+.zoom-current-view,
+.zoom-current-view-reverse,
+.zoom-previous-view,
+.zoom-previous-view-reverse,
+.zoom-last-view,
+.zoom-last-view-reverse,
+.zoom-lateral-back,
+.zoom-lateral-out,
+.zoom-lateral-in {
+  will-change:
+    transform,
+    opacity,
+    filter;
+}
+.z-view.has-effect {
+  transition: filter var(--zoom-duration, 1s) var(--zoom-ease, ease-in-out);
+  filter: var(--z-effect-filter, none);
+}
+.z-view.has-effect-reverse {
+  transition: filter var(--zoom-duration, 1s) var(--zoom-ease, ease-in-out);
+  filter: none;
+}
 .z-view.hide {
   opacity: 0;
-  content-visibility: hidden;
+}
+.zoom-me.z-trigger-hidden {
+  visibility: hidden;
+}
+.zoom-me.z-trigger-fade {
+  transition: opacity var(--zoom-duration, 1s) var(--zoom-ease, ease-in-out);
+  opacity: 0;
+}
+.zoom-me.z-trigger-fade-reverse {
+  transition: opacity var(--zoom-duration, 1s) var(--zoom-ease, ease-in-out);
+  opacity: 1;
+}
+.z-view.z-view-fade-in {
+  transition: opacity var(--zoom-duration, 1s) var(--zoom-ease, ease-in-out);
+  opacity: 1;
+}
+.z-view.z-view-fade-out {
+  transition: opacity var(--zoom-duration, 1s) var(--zoom-ease, ease-in-out);
+  opacity: 0;
 }
 .zoom-me {
   cursor: zoom-in;
 }
+.zoom-me[role=button] {
+  -webkit-tap-highlight-color: transparent;
+}
 .zoom-current-view-reverse {
   animation-name: zoom-current-view;
   animation-duration: var(--zoom-duration);
   animation-timing-function: var(--zoom-ease);
+  animation-fill-mode: both;
   animation-direction: reverse;
 }
 .zoom-current-view {
   animation-name: zoom-current-view;
   animation-duration: var(--zoom-duration);
   animation-timing-function: var(--zoom-ease);
+  animation-fill-mode: both;
 }
 @keyframes zoom-current-view {
   0% {
@@ -60,11 +104,13 @@
   animation-name: zoom-previous-view;
   animation-duration: var(--zoom-duration);
   animation-timing-function: var(--zoom-ease);
+  animation-fill-mode: both;
 }
 .zoom-previous-view-reverse {
   animation-name: zoom-previous-view;
   animation-duration: var(--zoom-duration);
   animation-timing-function: var(--zoom-ease);
+  animation-fill-mode: both;
   animation-direction: reverse;
 }
 @keyframes zoom-previous-view {
@@ -79,12 +125,14 @@
   animation-name: zoom-last-view;
   animation-duration: var(--zoom-duration);
   animation-timing-function: var(--zoom-ease);
+  animation-fill-mode: both;
   animation-direction: reverse;
 }
 .zoom-last-view {
   animation-name: zoom-last-view;
   animation-duration: var(--zoom-duration);
   animation-timing-function: var(--zoom-ease);
+  animation-fill-mode: both;
 }
 @keyframes zoom-last-view {
   0% {
@@ -94,3 +142,196 @@
     transform: var(--last-view-transform-end);
   }
 }
+.zoom-lateral-back {
+  animation: zoom-lateral-back var(--zoom-duration) var(--zoom-ease) forwards;
+}
+@keyframes zoom-lateral-back {
+  0% {
+    transform: var(--lateral-from);
+  }
+  100% {
+    transform: var(--lateral-to);
+  }
+}
+.zoom-lateral-out {
+  animation: zoom-lateral-out var(--zoom-duration) var(--zoom-ease) forwards;
+}
+@keyframes zoom-lateral-out {
+  0% {
+    transform: var(--lateral-out-from);
+    opacity: 1;
+  }
+  100% {
+    transform: var(--lateral-out-to);
+    opacity: 0;
+  }
+}
+.zoom-lateral-in {
+  animation: zoom-lateral-in var(--zoom-duration) var(--zoom-ease) forwards;
+}
+@keyframes zoom-lateral-in {
+  0% {
+    transform: var(--lateral-in-from);
+    opacity: 0;
+  }
+  100% {
+    transform: var(--lateral-in-to);
+    opacity: 1;
+  }
+}
+.z-nav {
+  position: absolute;
+  z-index: 10;
+  display: flex;
+  align-items: center;
+  gap: 0;
+  pointer-events: none;
+  background: rgba(0, 0, 0, 0.5);
+  backdrop-filter: blur(12px);
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  border-radius: 100px;
+  padding: 6px 10px;
+}
+.z-nav--bottom-center {
+  bottom: 20px;
+  left: 50%;
+  transform: translateX(-50%);
+}
+.z-nav--bottom-left {
+  bottom: 20px;
+  left: 20px;
+}
+.z-nav--bottom-right {
+  bottom: 20px;
+  right: 20px;
+}
+.z-nav--top-center {
+  top: 20px;
+  left: 50%;
+  transform: translateX(-50%);
+}
+.z-nav--top-left {
+  top: 20px;
+  left: 20px;
+}
+.z-nav--top-right {
+  top: 20px;
+  right: 20px;
+}
+.z-nav--middle-left {
+  top: 50%;
+  left: 16px;
+  transform: translateY(-50%);
+  flex-direction: column;
+}
+.z-nav--middle-right {
+  top: 50%;
+  right: 16px;
+  transform: translateY(-50%);
+  flex-direction: column;
+}
+.z-nav > * {
+  pointer-events: auto;
+}
+.z-nav-depth,
+.z-nav-lateral {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.z-nav-sep {
+  width: 1px;
+  height: 18px;
+  background: rgba(255, 255, 255, 0.15);
+  margin: 0 8px;
+  flex-shrink: 0;
+}
+.z-nav--middle-left .z-nav-depth,
+.z-nav--middle-left .z-nav-lateral,
+.z-nav--middle-right .z-nav-depth,
+.z-nav--middle-right .z-nav-lateral {
+  flex-direction: column;
+}
+.z-nav--middle-left .z-nav-depth-dots,
+.z-nav--middle-left .z-nav-lateral-dots,
+.z-nav--middle-right .z-nav-depth-dots,
+.z-nav--middle-right .z-nav-lateral-dots {
+  flex-direction: column;
+}
+.z-nav--middle-left .z-nav-sep,
+.z-nav--middle-right .z-nav-sep {
+  width: 18px;
+  height: 1px;
+  margin: 8px 0;
+}
+.z-nav--middle-left .z-nav-back,
+.z-nav--middle-right .z-nav-back {
+  transform: rotate(180deg);
+}
+.z-nav--middle-left .z-nav-prev,
+.z-nav--middle-right .z-nav-prev {
+  transform: rotate(90deg);
+}
+.z-nav--middle-left .z-nav-next,
+.z-nav--middle-right .z-nav-next {
+  transform: rotate(90deg);
+}
+.z-nav-back {
+  transform: rotate(90deg);
+}
+.z-nav-back,
+.z-nav-arrow {
+  width: 28px;
+  height: 28px;
+  border-radius: 50%;
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  background: rgba(255, 255, 255, 0.08);
+  color: #fff;
+  font-size: 1rem;
+  line-height: 1;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background 0.15s, border-color 0.15s;
+  padding: 0;
+}
+.z-nav-back:hover,
+.z-nav-arrow:hover:not(:disabled) {
+  background: rgba(255, 255, 255, 0.18);
+  border-color: rgba(255, 255, 255, 0.4);
+}
+.z-nav-arrow:disabled {
+  opacity: 0.2;
+  cursor: default;
+}
+.z-nav-depth-dots,
+.z-nav-lateral-dots {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+}
+.z-nav-dot {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  background: rgba(255, 255, 255, 0.15);
+  padding: 0;
+  cursor: default;
+  transition:
+    background 0.2s,
+    transform 0.2s,
+    border-color 0.2s;
+}
+.z-nav-lat-dot {
+  cursor: pointer;
+}
+.z-nav-lat-dot:hover {
+  background: rgba(255, 255, 255, 0.4);
+}
+.z-nav-dot.is-active {
+  background: #fff;
+  border-color: #fff;
+  transform: scale(1.35);
+}