@mnstry/atelier 0.2.0-alpha.16 → 0.2.0-alpha.17

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.0-alpha.17
+
+- Add UI primitives (`@mnstry/atelier/ui/primitives` and `/ui/primitives/browser`), the shared behaviour layer beside the control system. The carousel combines the Urana Heart site's carousel (seamless loops over inert clones, horizontal drag intent, flick steps, focus kept off inert slides, page dots and thumbnails, a polite live status, height that follows the slide, receding neighbours and a still row when every card fits, and a crossfade mode) with Botanika's additions (a draggable scroll bar, capped momentum for multi-card strips, page stepping that never reads as backwards in a short loop, and discrete or smooth autoplay with a pause control that holds on hover, focus, touch, wheel, drag, a hidden tab or off screen and never runs under reduced motion). A `visible` selection mode keeps every on-screen card interactive for product strips. Also: interruptible `<details>` disclosures, the counted layout-stable scroll lock from the portable presentation contract (measured from the body's laid-out width, so it holds with `scrollbar-gutter: stable`), and one motion owner. Pure state is exported for Node; tenants theme through `--system-carousel-*`. See the [UI primitives reference](docs/reference/ui-primitives.md).
+
 ## 0.2.0-alpha.16
 
 - Rename the graph workspace's room from constellation to **map** and its middle layer from coach to **distribution**. The runtime already holds *constellation* as an identity canonical (a grouping of people), and Atelier already defines the distribution tier. New names: `ROOMS` is `map`, `workbench`, `review`; `LAYERS` is `atelier`, `distribution`, `owner`; `planMap`, `createMap`, the shell handle's `map` and `backToMap`, `setBy: 'distribution'`; interface text says "map". The alpha.15 names keep working for this release and are removed in the next: `room: 'constellation'` (listed in the new `DEPRECATED_ROOMS`), `composeRecipes({ coach })` (giving both `coach` and `distribution` refuses), `planConstellation`, `createConstellation`, the handle's `constellation` and `backToConstellation`, and the element's `constellation` class.
@@ -316,6 +320,7 @@
 
 ## Unreleased
 
+- Document how a host locks page scrolling around the presentation's modal confirmation without shifting the layout (pay the hidden scrollbar back as body end padding, count locks), and test that the browser binding itself never changes the host page's overflow, padding or scroll position.
 - Patch the fast-uri dependency and override from 3.1.7 to 3.1.8, the patched
   3.x release for GHSA-hrr3-gc8f-f4qj (3.1.7 is in the affected range; whether
   Atelier's use was exploitable is not established). The direct dependency

package/README.md

@@ -1,6 +1,6 @@
 # MNSTRY Atelier
 
-`0.2.0-alpha.16` renames the [graph workspace](docs/guides/graph-workspace.md)'s room to the map and its middle layer to distribution, keeping the alpha.15 names for one release. `0.2.0-alpha.15` added the workspace (a map of every readable record, a focused authoring workbench and a review room, built from primitives distributions and owners can compose), renderer-neutral graph views and an [extension SDK and Postgres project workflow](docs/guides/extensions.md). Native host qualification remains a separate gate.
+`0.2.0-alpha.17` adds shared [UI primitives](docs/reference/ui-primitives.md): one carousel, disclosure, scroll lock and motion layer for Atelier-built sites. `0.2.0-alpha.16` renames the [graph workspace](docs/guides/graph-workspace.md)'s room to the map and its middle layer to distribution, keeping the alpha.15 names for one release. `0.2.0-alpha.15` added the workspace (a map of every readable record, a focused authoring workbench and a review room, built from primitives distributions and owners can compose), renderer-neutral graph views and an [extension SDK and Postgres project workflow](docs/guides/extensions.md). Native host qualification remains a separate gate.
 
 **Turn a repository into a living, governed system.**
 

package/docs/guides/upgrade.md

@@ -9,6 +9,13 @@ workspace between Atelier package releases. The flow is local-only: it does not
 provision repositories, contact a Git host, mutate the MNSTRY runtime, or write
 through a browser view.
 
+## Upgrading to 0.2.0-alpha.17
+
+This release only adds `@mnstry/atelier/ui/primitives` and
+`@mnstry/atelier/ui/primitives/browser`; nothing existing changes and no stored
+record changes format. The alpha.15 graph workspace names that alpha.16 kept
+for one release are still accepted here; their removal moves to a later release.
+
 ## Upgrading to 0.2.0-alpha.16
 
 This release renames two graph workspace names; nothing else changes and no

package/docs/reference/portable-presentation.md

@@ -119,6 +119,15 @@ request port because native has no browser default. A web host with unsaved work
 must omit item hrefs until safe navigation is available through its existing
 route/draft authority; this module does not install an unsaved-work route guard.
 Do not infer identical web/native navigation interception from shared labels.
+
+The confirmation is a native modal `<dialog>`. The binding never changes the
+host document's overflow, padding or scroll position, so opening it cannot
+shift the page. A host that also locks page scrolling while it is open owns that
+lock and must not let it shift the layout: measure the scrollbar it is about to
+hide (`innerWidth - documentElement.clientWidth`, zero for overlay scrollbars),
+add that width to the body's existing end padding, expose it as a custom
+property for fixed or sticky elements, and restore both when the last lock is
+released. Count locks so one closing overlay cannot release another. `lockScroll` and `unlockScroll` in [UI primitives](ui-primitives.md) implement this lock.
 Media resolves only local paths; hosts must prevent
 those routes from redirecting outside their intended boundary. The model is not
 a network-security boundary for a consumer's asset server.

package/docs/reference/ui-primitives.md

@@ -0,0 +1,116 @@
+# UI primitives
+
+`@mnstry/atelier/ui/primitives` is the shared behaviour layer for sites and apps
+built with Atelier. It sits beside the control system (`@mnstry/atelier/ui`) and
+follows the same rules: no tenant content, plain HTML contracts that work
+without script, and theming only through `--system-*` custom properties.
+
+| Import | Runs in | Provides |
+| --- | --- | --- |
+| `@mnstry/atelier/ui/primitives` | Node and browsers | Pure state functions, `carouselStyles`, `renderCarouselControls` |
+| `@mnstry/atelier/ui/primitives/browser` | Browsers | `enhanceCarousels`, `enhanceDisclosures`, `lockScroll` and `unlockScroll`, the motion owner |
+
+The carousel brings together the Urana Heart site's carousel (seamless loops,
+drag intent, focus safety, page dots and thumbnails, live status, height that
+follows the slide, receding neighbours, still rows) and Botanika's additions (a
+draggable scroll bar, momentum for multi-card strips, autoplay, a pause control).
+
+## Carousel
+
+### Markup contract
+
+```html
+<div class="system-carousel" data-carousel="track" data-select="visible" data-loop
+     data-autoplay="discrete" data-interval="6000"
+     role="region" aria-roledescription="carousel" aria-label="Featured collection">
+  <div data-carousel-viewport tabindex="0" aria-label="Featured collection, scroll horizontally">
+    <div data-carousel-track>
+      <article>…</article>
+      <article>…</article>
+    </div>
+  </div>
+  <!-- optional: page dots or thumbnails -->
+  <div class="system-carousel__pages">
+    <button type="button" class="system-carousel__page" data-page aria-label="Show slide 1">…</button>
+  </div>
+  <!-- controls and status: renderCarouselControls({ label, autoplay }) -->
+</div>
+```
+
+Without script, the viewport is a native horizontal scroller with snap points,
+so touch, trackpad, wheel and keyboard scrolling all work. Slides are the
+track's children; if any child carries `data-slide`, only those count.
+
+### Options (attributes on the root)
+
+| Attribute | Values | Effect |
+| --- | --- | --- |
+| `data-carousel` | `track` (default), `fade` | Scrolling strip, or slides crossfading in one grid cell |
+| `data-select` | `current` (default), `visible` | `current` makes every slide except the current one inert (slideshows); `visible` keeps every card on screen interactive (product strips) |
+| `data-step` | `item`, `page` | What an arrow moves. Defaults to `page` for `visible` and `item` for `current`. A loop barely longer than a page steps by the hidden remainder |
+| `data-loop` | present | Seamless loop over inert clones; arrows never stop |
+| `data-peek` | present | Centre-aligned slides; neighbours recede (`--d` from 0 to 1) and clicking one centres it; a still row when every card fits at `data-row-min` (default 400px) |
+| `data-fit` | `current` | The viewport height follows the slide in view, blending as slides pass |
+| `data-autoplay` | `off` (default), `discrete`, `smooth` | Advance one page every `data-interval` ms (at least 2500), or drift continuously at `data-speed` px/s |
+
+### Behaviour
+
+- **Mouse drag** on the slides: a drag starts only once horizontal movement
+  clearly dominates, so vertical page scrolling is never taken over. Clicks at
+  the end of a drag are swallowed; a plain click still follows its link.
+  Slideshows step one slide (distance or flick); `visible` strips glide with
+  capped momentum and settle on a card.
+- **Scroll bar** (`[data-scrollbar]`): click to jump, or drag the thumb. It
+  covers one set of slides in a loop.
+- **Arrows, pages and keys:** Previous, Next, page buttons, and Left, Right,
+  Home and End on the carousel. Reader-initiated moves are announced politely in
+  `[data-status]`; autoplay moves are not.
+- **Autoplay** never runs under reduced motion. It holds while the pointer is
+  over the carousel, while focus is inside it, during a touch, wheel, drag or
+  scrub, while the tab is hidden and while the carousel is off screen. The
+  rendered toggle pauses and resumes it. `data-autoplay-state` reads `playing`,
+  `held`, `paused` or `off`.
+- **Focus:** before a slide becomes inert, focus moves to its page button or
+  another control, so it is never lost.
+
+The enhancer sets `data-ready`, `data-overflow`, `data-row`, `data-dragging`
+and `data-scrubbing` for styling, and hides the controls when nothing overflows.
+`enhanceCarousel(root)` returns `{ go, goTo, pause, play }`.
+
+### Theming
+
+Use `carouselStyles` once per page (for example
+`<style set:html={carouselStyles}>`) and set custom properties on the carousel:
+
+`--system-carousel-gap`, `-slide` (slide width), `-inset` (full-bleed side
+padding), `-align`, `-ease`, `-focus`, `-button-size`, `-button-border`,
+`-button-radius`, `-button-background`, `-button-hover-background`,
+`-button-hover-border`, `-controls-justify`, `-controls-gap`,
+`-controls-offset`, `-scrollbar-width`, `-scrollbar-thickness`,
+`-scrollbar-track`, `-scrollbar-thumb`, `-thumb-width`, `-thumb-height`,
+`-thumb-current`, `-recede-scale`, `-recede-fade`, `-fade-ms`.
+
+## Disclosures
+
+`enhanceDisclosures(root)` animates native `<details>`: open and close can be
+reversed mid-way, `data-state` (`open` or `closed`) follows the reader's intent
+at once so icons turn with the click, and reduced motion opens instantly.
+Keyboard and no-script behaviour stay native.
+
+## Scroll lock
+
+`lockScroll(owner)` and `unlockScroll(owner)` implement the layout-stable host
+lock described in [portable presentation](portable-presentation.md). The lock
+hides page scrolling, pays the hidden scrollbar back as body end padding,
+exposes it as `--scroll-lock-gap` for fixed and sticky elements (for example
+`right: var(--scroll-lock-gap, 0px)` on a fixed panel), and counts owners so one
+closing overlay cannot release another. The gap is measured as the growth of the
+body's laid-out width, which stays correct with `scrollbar-gutter: stable` and
+with overlay scrollbars.
+
+## Motion
+
+`animationAllowed()`, `onMotionChange(listener)` and `animate(element, frames,
+options)` give one owner for motion: the reduced-motion preference and hidden
+tabs stop every effect started through them. `startMotionWatch()` begins
+watching; the carousel and disclosures call it as needed.

package/fixtures/templates/local-library.v1.json

@@ -70,7 +70,8 @@
       "0.2.0-alpha.13",
       "0.2.0-alpha.14",
       "0.2.0-alpha.15",
-      "0.2.0-alpha.16"
+      "0.2.0-alpha.16",
+      "0.2.0-alpha.17"
     ],
     "packRefs": []
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnstry/atelier",
-  "version": "0.2.0-alpha.16",
+  "version": "0.2.0-alpha.17",
   "private": false,
   "description": "Local toolkit that turns a Git repository into an ontology-governed knowledge graph, enforcement layer, and runtime for people, agents, and tools. No telemetry or required hosted account; optional host-bound vault adapters.",
   "keywords": [
@@ -64,6 +64,8 @@
     "./readiness-protocols": "./src/readiness-protocols/bundled-pack.mjs",
     "./server": "./src/server/local-sidecar.mjs",
     "./ui": "./src/ui/control-system.mjs",
+    "./ui/primitives": "./src/ui/primitives/index.mjs",
+    "./ui/primitives/browser": "./src/ui/primitives/browser.mjs",
     "./harness": "./src/harness/context.mjs",
     "./collaboration": "./src/collaboration/index.mjs",
     "./support": "./src/support/support-bundle.mjs",

package/src/ui/primitives/browser.mjs

@@ -0,0 +1,6 @@
+/** Atelier UI primitives for the browser. */
+export { enhanceCarousels, enhanceCarousel } from './carousel.mjs'
+export { enhanceDisclosures } from './disclosure.mjs'
+export { lockScroll, unlockScroll, scrollLocked } from './scroll-lock.mjs'
+export { animate, animationAllowed, onMotionChange, startMotionWatch } from './motion.mjs'
+export * from './state.mjs'

package/src/ui/primitives/carousel.mjs

@@ -0,0 +1,551 @@
+/**
+ * Carousel enhancer (browser). Progressive enhancement over plain HTML: without
+ * script every slide is a native horizontal scroller (track) or a stacked list
+ * (fade). See docs/reference/ui-primitives.md for the markup contract.
+ *
+ * Track carousels scroll natively (CSS scroll snap), so touch, trackpad, wheel
+ * and keyboard keep the platform's physics. Script adds seamless loops over
+ * inert clones, mouse drag (with momentum for multi-card strips), a draggable
+ * scroll bar, arrows, pages or thumbnails, a live status, height that follows
+ * the current slide, receding neighbours, a still row when every card fits,
+ * and discrete or smooth autoplay with a pause control.
+ */
+import {
+  arrowStep, autoplayConfig, dragIntent, driftStep, glideStep, homeIndex, loopSets, nearestCopy, releaseVelocity,
+  pageSize, recede, rowFit, scrubPosition, slideWindow, swipeStep, thumbGeometry, wrap,
+} from './state.mjs'
+import { animationAllowed, onMotionChange } from './motion.mjs'
+
+const q = (root, selectors) => root.querySelector(selectors)
+const qa = (root, selectors) => [...root.querySelectorAll(selectors)]
+const finePointer = () => matchMedia('(hover: hover) and (pointer: fine)').matches
+
+// Move keyboard focus before its slide becomes inert or hidden.
+function focusAvailable(candidates, reveal = false) {
+  const target = candidates.find(element => element && !element.matches(':disabled') && !element.closest('[inert], [hidden]') && element.getClientRects().length && getComputedStyle(element).visibility !== 'hidden')
+  target?.focus({ preventScroll: !reveal })
+  return !!target && document.activeElement === target
+}
+function revealControlFocus(controls) {
+  const focused = document.activeElement
+  if (focused instanceof HTMLElement && controls?.contains(focused) && focused.getClientRects().length) focused.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: 'instant' })
+}
+function preserveSlideFocus(slides, shown, control) {
+  if (!slides.some(slide => slide !== shown && slide.contains(document.activeElement))) return
+  const controls = control?.closest('[data-controls]')
+  focusAvailable([control, ...(controls ? controls.querySelectorAll('button') : [])])
+}
+
+/** Enhance every `[data-carousel]` under `root`. Safe to call more than once. */
+export function enhanceCarousels(root = document) {
+  return qa(root, '[data-carousel]').map(enhanceCarousel).filter(Boolean)
+}
+
+export function enhanceCarousel(root) {
+  if (root.dataset.ready !== undefined) return null
+  const track = q(root, '[data-carousel-track], .carousel__track')
+  if (!track) return null
+  // Slides are the track's children; `data-slide` narrows that when a track holds other elements.
+  const children = [...track.children].filter(element => !element.hasAttribute('data-clone'))
+  const slides = children.some(element => element.hasAttribute('data-slide')) ? children.filter(element => element.hasAttribute('data-slide')) : children
+  const parts = {
+    root, track, slides, n: slides.length,
+    label: root.getAttribute('aria-label') ?? 'Carousel',
+    viewport: q(root, '[data-carousel-viewport], .carousel__viewport') || track,
+    controls: q(root, '[data-controls]'),
+    back: q(root, '[data-prev]'),
+    next: q(root, '[data-next]'),
+    pages: qa(root, '[data-page]'),
+    status: q(root, '[data-status]'),
+    count: q(root, '[data-count]'),
+    scrollbar: q(root, '[data-scrollbar]'),
+    toggle: q(root, '[data-autoplay-toggle]'),
+    autoplay: autoplayConfig({ mode: root.dataset.autoplay, interval: root.dataset.interval, speed: root.dataset.speed }),
+  }
+  if (parts.n < 2) { if (parts.controls) parts.controls.hidden = true; root.dataset.ready = ''; return null }
+  slides.forEach((slide, i) => {
+    slide.setAttribute('role', 'group')
+    slide.setAttribute('aria-roledescription', 'slide')
+    if (!slide.hasAttribute('aria-label')) slide.setAttribute('aria-label', `${i + 1} of ${parts.n}`)
+  })
+  root.querySelectorAll('img, a').forEach(element => element.setAttribute('draggable', 'false'))
+  // Thumbnail pages without their own image show the slide's image.
+  parts.pages.forEach((page, i) => {
+    if (!page.hasAttribute('data-thumb') || page.querySelector('img')) return
+    const img = slides[i]?.querySelector('img')
+    const set = () => img?.currentSrc && page.style.setProperty('--thumb', `url("${img.currentSrc}")`)
+    img?.complete ? set() : img?.addEventListener('load', set, { once: true })
+  })
+  return root.dataset.carousel === 'fade' ? initFade(parts) : initTrack(parts)
+}
+
+/* ------------------------------------------------------------------ autoplay */
+
+function createAutoplay({ root, toggle, autoplay }, { advance, startDrift, stopDrift, canRun }) {
+  const reasons = new Set()
+  let userPaused = root.dataset.autoplayPaused !== undefined
+  let onScreen = true
+  let timer = 0
+  const enabled = () => autoplay.mode !== 'off' && animationAllowed() && canRun()
+  const running = () => enabled() && !userPaused && !reasons.size && onScreen
+  const stop = () => { clearTimeout(timer); timer = 0; stopDrift() }
+  const start = () => {
+    stop()
+    if (!running()) return
+    if (autoplay.mode === 'discrete') timer = setTimeout(() => { advance(); start() }, autoplay.interval)
+    else startDrift()
+  }
+  const sync = () => {
+    root.dataset.autoplayState = enabled() ? (userPaused ? 'paused' : reasons.size ? 'held' : 'playing') : 'off'
+    if (!toggle) return
+    toggle.hidden = !enabled()
+    toggle.setAttribute('aria-label', userPaused ? 'Play automatic scrolling' : 'Pause automatic scrolling')
+    toggle.dataset.state = userPaused ? 'paused' : 'playing'
+  }
+  const hold = reason => { reasons.add(reason); stop(); sync() }
+  const release = (reason, delay = 0) => {
+    const go = () => { reasons.delete(reason); start(); sync() }
+    delay ? setTimeout(go, delay) : go()
+  }
+  if (autoplay.mode !== 'off') {
+    toggle?.addEventListener('click', () => { userPaused = !userPaused; start(); sync() })
+    root.addEventListener('mouseenter', () => { if (finePointer()) hold('hover') })
+    root.addEventListener('mouseleave', () => release('hover'))
+    root.addEventListener('focusin', event => { if (!toggle?.contains(event.target)) hold('focus') })
+    root.addEventListener('focusout', event => { if (!root.contains(event.relatedTarget)) release('focus') })
+    root.addEventListener('pointerdown', event => { if (event.pointerType !== 'mouse') hold('touch') })
+    const lift = event => { if (event.pointerType !== 'mouse') release('touch', 2500) }
+    root.addEventListener('pointerup', lift)
+    root.addEventListener('pointercancel', lift)
+    let wheelTimer = 0
+    root.addEventListener('wheel', () => { hold('wheel'); clearTimeout(wheelTimer); wheelTimer = setTimeout(() => release('wheel'), 2500) }, { passive: true })
+    onMotionChange(() => { start(); sync() })
+    if ('IntersectionObserver' in window) new IntersectionObserver(entries => { onScreen = entries.some(entry => entry.isIntersecting); start(); sync() }, { threshold: 0.25 }).observe(root)
+  }
+  return { start, stop, hold, release, sync, restart: () => { if (autoplay.mode === 'discrete') start() }, smooth: autoplay.mode === 'smooth', active: running }
+}
+
+/* ------------------------------------------------------------- scroll bar */
+
+function bindScrollbar({ root, scrollbar }, { geometry, scrubTo, begin, end }) {
+  const thumb = scrollbar?.querySelector('span, [data-scrollbar-thumb]')
+  if (!scrollbar || !thumb) return () => {}
+  scrollbar.addEventListener('pointerdown', event => {
+    if (event.button > 0) return
+    event.preventDefault()
+    const rail = scrollbar.getBoundingClientRect()
+    const box = thumb.getBoundingClientRect()
+    const onThumb = event.clientX >= box.left && event.clientX <= box.right
+    const grab = onThumb ? event.clientX - box.left : box.width / 2
+    scrollbar.setPointerCapture(event.pointerId)
+    root.dataset.scrubbing = ''
+    begin()
+    const move = x => scrubTo(scrubPosition(x, rail.left, rail.width, box.width, grab, geometry().range))
+    move(event.clientX)
+    const onMove = moveEvent => move(moveEvent.clientX)
+    const onUp = () => { scrollbar.removeEventListener('pointermove', onMove); delete root.dataset.scrubbing; end() }
+    scrollbar.addEventListener('pointermove', onMove)
+    scrollbar.addEventListener('pointerup', onUp, { once: true })
+    scrollbar.addEventListener('pointercancel', onUp, { once: true })
+  })
+  return () => {
+    const { position, range, viewport } = geometry()
+    const { width, left } = thumbGeometry(position, range, viewport)
+    thumb.style.width = `${width * 100}%`
+    thumb.style.left = `${left * 100}%`
+    scrollbar.hidden = range <= 1
+  }
+}
+
+/* ------------------------------------------------------------------ track */
+
+function initTrack(parts) {
+  const { root, viewport, track, slides, n, label, controls, back, next, pages, status, count } = parts
+  const loop = root.hasAttribute('data-loop')
+  const peek = root.hasAttribute('data-peek') || root.classList.contains('carousel--peek')
+  // select="current": one slide is current and the rest are inert (slideshows).
+  // select="visible": every card on screen stays interactive (product strips).
+  const visibleMode = root.dataset.select === 'visible'
+  const pageStep = (root.dataset.step || (visibleMode ? 'page' : 'item')) === 'page'
+  // fit="current": the strip is as tall as the slide in view, blending between heights as they pass.
+  const fitCurrent = root.dataset.fit === 'current'
+  const rowMin = Number(root.dataset.rowMin) || 400
+  let sets = 0
+  let items = slides
+  let step = 0, current = -1, target = null, announce = false, row = false, timer = 0, realigned = false
+  let home = 0, intent = false, drifting = false, gliding = 0, scrubbing = false
+  let heights = [], padY = 0, padTop = 0
+  let drag = null, suppressClick = false
+
+  const buildClones = perSide => {
+    track.querySelectorAll('[data-clone]').forEach(clone => clone.remove())
+    sets = loop ? loopSets(n, perSide) : 0
+    if (sets) {
+      const clone = slide => {
+        const copy = slide.cloneNode(true)
+        copy.removeAttribute('id'); copy.querySelectorAll('[id]').forEach(element => element.removeAttribute('id'))
+        copy.dataset.clone = ''; copy.inert = true; copy.setAttribute('aria-hidden', 'true')
+        return copy
+      }
+      const copies = () => Array.from({ length: sets }, () => slides.map(clone)).flat()
+      track.prepend(...copies()); track.append(...copies())
+    }
+    items = [...track.children]
+  }
+  const first = () => sets * n
+  const position = () => (step ? viewport.scrollLeft / step : 0)
+  const scrollToIndex = (index, smooth) => viewport.scrollTo({ left: index * step, behavior: smooth && animationAllowed() ? 'smooth' : 'instant' })
+  const perPage = () => (pageStep ? arrowStep(pageSize(viewport.clientWidth, step), n, loop) : 1)
+  const lastIndex = () => (step ? Math.max(0, Math.round((viewport.scrollWidth - viewport.clientWidth) / step)) : 0)
+
+  const fitHeight = pos => {
+    if (!fitCurrent || row || !heights.length) return
+    const a = Math.floor(pos), h = i => heights[((i % n) + n) % n]
+    viewport.style.height = `${h(a) + (h(a + 1) - h(a)) * (pos - a) + padY}px`
+  }
+  const placeArrows = () => {
+    const middle = fitCurrent && heights.length ? padTop + Math.min(...heights) / 2 : viewport.offsetHeight / 2
+    root.style.setProperty('--mid', `${viewport.offsetTop + middle}px`)
+  }
+  const measureHeights = () => {
+    if (!fitCurrent) return
+    const style = getComputedStyle(viewport)
+    padTop = parseFloat(style.paddingTop); padY = padTop + parseFloat(style.paddingBottom)
+    heights = slides.map(slide => slide.offsetHeight)
+  }
+
+  const geometry = () => {
+    if (sets) {
+      const period = n * step
+      return { position: wrap(viewport.scrollLeft - first() * step, period), range: Math.max(0, period - viewport.clientWidth), viewport: viewport.clientWidth }
+    }
+    return { position: viewport.scrollLeft, range: Math.max(0, viewport.scrollWidth - viewport.clientWidth), viewport: viewport.clientWidth }
+  }
+  const paintScrollbar = bindScrollbar(parts, {
+    geometry,
+    scrubTo: offset => { viewport.scrollLeft = (sets ? first() * step : 0) + offset },
+    begin: () => { stopGlide(); scrubbing = true; intent = true; viewport.style.scrollSnapType = 'none'; player.hold('scrub') },
+    end: () => { scrubbing = false; intent = true; settleSoon(); player.release('scrub') },
+  })
+
+  const paint = () => {
+    if (row || !step) return
+    const pos = position(), c = Math.max(0, Math.min(items.length - 1, Math.round(pos)))
+    if (peek) items.forEach((item, i) => item.style.setProperty('--d', recede(pos, i).toFixed(3)))
+    fitHeight(pos)
+    paintScrollbar()
+    if (c === current) return
+    current = c
+    if (!loop && back && next) { back.disabled = c <= 0; next.disabled = c >= lastIndex() }
+    if (!visibleMode) preserveSlideFocus(items, items[c], pages[c % n])
+    items.forEach((item, i) => {
+      const shown = i === c
+      item.classList.toggle('is-current', shown)
+      if (!visibleMode && !item.hasAttribute('data-clone')) { item.inert = !shown; item.toggleAttribute('aria-hidden', !shown) }
+    })
+    pages.forEach((page, i) => page.setAttribute('aria-current', String(i === c % n)))
+    if (count) count.textContent = `${(c % n) + 1} / ${n}`
+  }
+
+  // Once still: step back onto the real slide showing the same content (identical, so invisible).
+  const settle = () => {
+    if (row || !step || drag || gliding || scrubbing) return
+    if (drifting) return
+    if (player.smooth && player.active()) return
+    if (!intent) {
+      if (!player.smooth) viewport.style.removeProperty('scroll-snap-type')
+      const goal = (first() + home) * step
+      if (Math.abs(viewport.scrollLeft - Math.min(goal, viewport.scrollWidth - viewport.clientWidth)) > 1) scrollToIndex(first() + home, false)
+      paint(); return
+    }
+    const c = Math.round(position())
+    if (!player.smooth && !realigned && Math.abs(viewport.scrollLeft - c * step) > 2 && c < lastIndex()) {
+      realigned = true; viewport.style.removeProperty('scroll-snap-type'); scrollToIndex(c, true)
+      if (!animationAllowed()) settle()
+      return
+    }
+    realigned = false
+    if (sets && (c < first() || c >= first() + n)) viewport.scrollTo({ left: viewport.scrollLeft + (homeIndex(c, n, sets) - c) * step, behavior: 'instant' })
+    home = ((Math.round(position()) % n) + n) % n
+    if (!sets) home = Math.round(position())
+    intent = false; target = null
+    if (!player.smooth) viewport.style.removeProperty('scroll-snap-type')
+    paint()
+    if (announce && status) { status.textContent = `${label}: ${(current % n) + 1} of ${n}`; announce = false }
+  }
+  const settleSoon = () => { if (!('onscrollend' in window)) { clearTimeout(timer); timer = setTimeout(settle, 140) } else requestAnimationFrame(() => settle()) }
+
+  const go = (delta, { user = true } = {}) => {
+    if (row || !step) return
+    stopGlide()
+    intent = true
+    let base = target ?? Math.round(position())
+    if (sets) {
+      const equivalent = homeIndex(base, n, sets)
+      if (equivalent !== base) { viewport.scrollTo({ left: viewport.scrollLeft + (equivalent - base) * step, behavior: 'instant' }); base = equivalent }
+    } else if (loop && delta > 0 && base >= lastIndex()) {
+      delta = -base // a loop too short for clones still wraps
+    } else if (loop && delta < 0 && base <= 0) {
+      delta = lastIndex()
+    }
+    const to = sets ? base + delta : Math.max(0, Math.min(lastIndex(), base + delta))
+    target = to; announce = user
+    scrollToIndex(to, true)
+  }
+  const goTo = index => go(sets ? nearestCopy(target ?? Math.round(position()), index, n) : index - (target ?? Math.round(position())))
+
+  const measure = () => {
+    const focusedSlide = slides.findIndex(slide => slide.contains(document.activeElement))
+    const keep = row && focusedSlide >= 0 ? focusedSlide : home
+    home = keep
+    const controlFocused = controls?.contains(document.activeElement)
+    const focusedPage = pages.findIndex(page => page.contains(document.activeElement))
+    root.style.removeProperty('--slide-fit'); delete root.dataset.row
+    const gap = parseFloat(getComputedStyle(track).columnGap) || 0
+    const fit = peek ? rowFit(n, slides[0].offsetWidth, gap, root.clientWidth, rowMin) : 0
+    row = fit > 0
+    viewport.style.removeProperty('height')
+    if (row) {
+      root.dataset.row = ''; root.style.setProperty('--slide-fit', `${fit}px`)
+      slides.forEach(slide => { slide.inert = false; slide.removeAttribute('aria-hidden'); slide.classList.remove('is-current'); slide.style.removeProperty('--d') })
+      if (controlFocused) {
+        const shown = slides[focusedPage >= 0 ? focusedPage : keep]
+        if (!focusAvailable([...shown.querySelectorAll('a[href], button, [tabindex]:not([tabindex="-1"])')], true)) { root.tabIndex = -1; root.focus() }
+      }
+      if (controls) controls.hidden = true
+      current = -1
+      return
+    }
+    // Fractional widths matter: offsetLeft rounds, and the error grows per card.
+    const width = parseFloat(getComputedStyle(slides[0]).width)
+    step = width + gap
+    root.style.setProperty('--slide-px', `${width}px`)
+    const fitsAll = !sets && viewport.scrollWidth - viewport.clientWidth <= 1
+    if (loop) {
+      const needed = pageSize(viewport.clientWidth, step) + (peek ? 4 : 1)
+      if (!sets || loopSets(n, needed) !== sets) buildClones(needed)
+      // A loop that cannot fill the screen with one set falls back to plain wrapping arrows.
+      if (n * step < viewport.clientWidth) { track.querySelectorAll('[data-clone]').forEach(clone => clone.remove()); sets = 0; items = slides }
+    }
+    root.dataset.overflow = String(!(fitsAll || (!sets && viewport.scrollWidth - viewport.clientWidth <= 1)))
+    if (controls) controls.hidden = root.dataset.overflow === 'false'
+    measureHeights()
+    current = -1; target = null
+    scrollToIndex(first() + keep, false)
+    paint()
+    placeArrows()
+    revealControlFocus(controls)
+    player.sync()
+  }
+
+  // Momentum for multi-card strips; slideshows step one slide per swipe instead.
+  function stopGlide() { cancelAnimationFrame(gliding); gliding = 0 }
+  const glide = velocity => {
+    if (!animationAllowed() || Math.abs(velocity) < 0.05) { settle(); return }
+    let last = performance.now(), pos = viewport.scrollLeft
+    const frame = now => {
+      const next = glideStep(pos, velocity, now - last)
+      last = now; pos = next.position; velocity = next.velocity
+      viewport.scrollLeft = pos
+      const atEdge = !sets && (pos <= 0 || pos >= viewport.scrollWidth - viewport.clientWidth)
+      if (Math.abs(velocity) > 0.03 && !atEdge) gliding = requestAnimationFrame(frame)
+      else { gliding = 0; settle() }
+    }
+    gliding = requestAnimationFrame(frame)
+  }
+
+  // Smooth autoplay keeps its own sub-pixel position so slow speeds never stall on rounding.
+  let driftFrame = 0
+  const player = createAutoplay(parts, {
+    advance: () => go(perPage(), { user: false }),
+    canRun: () => !row && root.dataset.overflow !== 'false',
+    startDrift: () => {
+      drifting = true
+      viewport.style.scrollSnapType = 'none'
+      let pos = viewport.scrollLeft, last = 0
+      const frame = now => {
+        if (last) {
+          if (sets) pos = first() * step + driftStep(pos - first() * step, parts.autoplay.speed, now - last, n * step)
+          else pos = driftStep(pos, parts.autoplay.speed, now - last, 0, viewport.scrollWidth - viewport.clientWidth)
+          viewport.scrollLeft = pos
+        }
+        last = now
+        driftFrame = requestAnimationFrame(frame)
+      }
+      driftFrame = requestAnimationFrame(frame)
+    },
+    stopDrift: () => {
+      if (!driftFrame) return
+      cancelAnimationFrame(driftFrame); driftFrame = 0; drifting = false
+      home = ((Math.round(position()) - first()) % n + n) % n
+    },
+  })
+  if (player.smooth) root.dataset.drift = ''
+
+  viewport.addEventListener('scroll', () => {
+    requestAnimationFrame(paint)
+    if (!('onscrollend' in window)) { clearTimeout(timer); timer = setTimeout(settle, 140) }
+  }, { passive: true })
+  viewport.addEventListener('scrollend', settle)
+  const user = () => { intent = true; stopGlide() }
+  for (const type of ['pointerdown', 'touchstart', 'wheel', 'keydown']) viewport.addEventListener(type, user, { passive: true })
+
+  back?.addEventListener('click', () => { go(-perPage()); player.restart() })
+  next?.addEventListener('click', () => { go(perPage()); player.restart() })
+  pages.forEach((page, i) => page.addEventListener('click', () => { goTo(i); player.restart() }))
+  root.addEventListener('keydown', event => {
+    if (row || event.altKey || event.ctrlKey || event.metaKey) return
+    if (event.target.closest?.('input, select, textarea, [contenteditable]')) return
+    const keys = { ArrowLeft: () => go(-1), ArrowRight: () => go(1), Home: () => goTo(0), End: () => goTo(n - 1) }
+    if (!keys[event.key]) return
+    event.preventDefault(); keys[event.key]()
+  })
+
+  // Mouse drag (touch and trackpads already scroll natively): follow the pointer, then settle.
+  root.addEventListener('pointerdown', event => {
+    if (row || event.pointerType !== 'mouse' || event.button !== 0 || event.target.closest('button, [data-scrollbar], input, select, textarea')) return
+    if (!viewport.contains(event.target)) return
+    stopGlide()
+    drag = { id: event.pointerId, x: event.clientX, y: event.clientY, t: event.timeStamp, left: viewport.scrollLeft, state: 'pending', samples: [{ x: event.clientX, t: event.timeStamp }] }
+    suppressClick = false
+  })
+  root.addEventListener('pointermove', event => {
+    if (!drag || event.pointerId !== drag.id) return
+    const dx = event.clientX - drag.x, dy = event.clientY - drag.y
+    if (drag.state === 'pending') {
+      drag.state = dragIntent(dx, dy)
+      if (drag.state === 'vertical') { drag = null; return }
+      if (drag.state === 'horizontal') {
+        root.setPointerCapture(event.pointerId); root.dataset.dragging = ''
+        viewport.style.scrollSnapType = 'none'; intent = true; player.hold('drag')
+      }
+    }
+    if (drag.state === 'horizontal') {
+      viewport.scrollLeft = drag.left - dx
+      drag.samples.push({ x: event.clientX, t: event.timeStamp })
+      if (drag.samples.length > 6) drag.samples.shift()
+    }
+  })
+  const release = (event, cancelled) => {
+    if (!drag || event.pointerId !== drag.id) return
+    const { x, y, t, left, state, samples } = drag
+    drag = null; delete root.dataset.dragging
+    if (state !== 'horizontal') return
+    suppressClick = true
+    player.release('drag')
+    if (visibleMode || player.smooth) {
+      const a = samples[0], b = samples.at(-1)
+      glide(cancelled ? 0 : releaseVelocity(b.x - a.x, b.t - a.t))
+      return
+    }
+    const start = Math.round(left / step), near = Math.round(position())
+    const flick = cancelled ? 0 : swipeStep(event.clientX - x, event.clientY - y, event.timeStamp - t)
+    let to = near === start ? start + flick : near
+    if (!sets) to = Math.max(0, Math.min(lastIndex(), to))
+    announce = to !== start; target = to
+    scrollToIndex(to, true)
+    if (Math.abs(viewport.scrollLeft - to * step) < 1) settle()
+  }
+  root.addEventListener('pointerup', event => release(event, false))
+  root.addEventListener('pointercancel', event => release(event, true))
+  root.addEventListener('dragstart', event => event.preventDefault())
+  root.addEventListener('click', event => {
+    if (suppressClick) { event.preventDefault(); event.stopPropagation(); suppressClick = false; return }
+    // A click on a receding neighbour brings it to the centre instead of following its link.
+    if (visibleMode || !peek || row || !step || event.detail === 0 || !viewport.contains(event.target)) return
+    const box = viewport.getBoundingClientRect()
+    const offset = Math.round((event.clientX - (box.left + box.width / 2)) / step)
+    if (offset) { event.preventDefault(); event.stopPropagation(); go(offset) }
+  }, true)
+
+  let lastWidth = 0
+  new ResizeObserver(() => requestAnimationFrame(() => { const w = root.clientWidth; if (Math.abs(w - lastWidth) > 0.5) { lastWidth = w; measure() } })).observe(root)
+  if (fitCurrent) {
+    const watch = new ResizeObserver(() => requestAnimationFrame(() => { if (row || !step) return; measureHeights(); fitHeight(position()); placeArrows() }))
+    slides.forEach(slide => watch.observe(slide))
+  }
+  root.dataset.ready = ''
+  measure()
+  player.start()
+  player.sync()
+  return { root, go, goTo, pause: () => player.hold('api'), play: () => player.release('api') }
+}
+
+/* ------------------------------------------------------------------- fade */
+
+function initFade(parts) {
+  const { root, viewport, slides, n, label, controls, back, next, pages, status, count } = parts
+  const loop = root.hasAttribute('data-loop')
+  const fit = root.dataset.fit === 'current'
+  let active = 0
+  const fitHeight = () => { if (fit) viewport.style.height = `${slides[active].offsetHeight}px` }
+  const placeArrows = () => {
+    const height = fit ? Math.min(...slides.map(slide => slide.offsetHeight)) : viewport.offsetHeight
+    root.style.setProperty('--mid', `${viewport.offsetTop + height / 2}px`)
+  }
+  let lastWidth = root.clientWidth
+  const watch = new ResizeObserver(() => requestAnimationFrame(() => {
+    const width = root.clientWidth, resized = Math.abs(width - lastWidth) > 0.5
+    lastWidth = width
+    fitHeight(); placeArrows()
+    if (resized) revealControlFocus(controls)
+  }))
+  watch.observe(root); slides.forEach(slide => watch.observe(slide))
+  const render = announce => {
+    const state = slideWindow(active, n, 1, loop)
+    active = state.start
+    if (back) back.disabled = state.previousDisabled
+    if (next) next.disabled = state.nextDisabled
+    preserveSlideFocus(slides, slides[active], pages[active])
+    slides.forEach((slide, i) => { const shown = i === active; slide.classList.toggle('is-current', shown); slide.inert = !shown })
+    pages.forEach((page, i) => page.setAttribute('aria-current', String(i === active)))
+    if (count) count.textContent = `${active + 1} / ${n}`
+    fitHeight()
+    if (announce && status) status.textContent = `${label}: ${active + 1} of ${n}`
+    root.dispatchEvent(new CustomEvent('carousel:change', { detail: { index: active } }))
+  }
+  const go = (targetIndex, announce = true) => { active = loop ? ((targetIndex % n) + n) % n : Math.max(0, Math.min(n - 1, targetIndex)); render(announce) }
+  const player = createAutoplay(parts, { advance: () => go(active + 1, false), canRun: () => true, startDrift: () => {}, stopDrift: () => {} })
+
+  back?.addEventListener('click', () => { go(active - 1); player.restart() })
+  next?.addEventListener('click', () => { go(active + 1); player.restart() })
+  pages.forEach((page, i) => page.addEventListener('click', () => { go(i); player.restart() }))
+  root.addEventListener('keydown', event => {
+    if (event.altKey || event.ctrlKey || event.metaKey) return
+    const keys = { ArrowLeft: () => go(active - 1), ArrowRight: () => go(active + 1), Home: () => go(0), End: () => go(n - 1) }
+    if (!keys[event.key]) return
+    event.preventDefault(); keys[event.key]()
+  })
+
+  // Swipes: a horizontal gesture changes slide; a vertical one stays a page scroll.
+  let drag = null, suppressClick = false
+  root.addEventListener('pointerdown', event => {
+    if (!event.isPrimary || event.button > 0 || event.target.closest('button')) return
+    drag = { id: event.pointerId, x: event.clientX, y: event.clientY, t: event.timeStamp, state: 'pending' }
+    suppressClick = false
+  })
+  root.addEventListener('pointermove', event => {
+    if (!drag || event.pointerId !== drag.id || drag.state !== 'pending') return
+    drag.state = dragIntent(event.clientX - drag.x, event.clientY - drag.y)
+    if (drag.state === 'vertical') drag = null
+    else if (drag.state === 'horizontal') { root.setPointerCapture(event.pointerId); root.dataset.dragging = '' }
+  })
+  const release = (event, cancelled) => {
+    if (!drag || event.pointerId !== drag.id) return
+    const horizontal = drag.state === 'horizontal', delta = cancelled ? 0 : swipeStep(event.clientX - drag.x, event.clientY - drag.y, event.timeStamp - drag.t)
+    drag = null; delete root.dataset.dragging
+    if (!horizontal) return
+    suppressClick = true
+    if (delta) { go(active + delta); player.restart() }
+  }
+  root.addEventListener('pointerup', event => release(event, false))
+  root.addEventListener('pointercancel', event => release(event, true))
+  root.addEventListener('click', event => { if (suppressClick) { event.preventDefault(); event.stopPropagation(); suppressClick = false } }, true)
+
+  if (controls) controls.hidden = false
+  root.dataset.ready = ''
+  render(false)
+  placeArrows()
+  player.start(); player.sync()
+  return { root, go, pause: () => player.hold('api'), play: () => player.release('api') }
+}

package/src/ui/primitives/disclosure.mjs

@@ -0,0 +1,50 @@
+/**
+ * Native <details> disclosures with interruptible open and close motion
+ * (browser). Keyboard and no-script behaviour stay native. data-state follows
+ * the reader's intent at once, so icons turn with the click while the panel
+ * is still moving. Reduced motion opens and closes instantly.
+ */
+import { animationAllowed } from './motion.mjs'
+
+const PROPERTIES = ['height', 'paddingTop', 'paddingBottom', 'marginTop', 'marginBottom', 'opacity']
+
+export function enhanceDisclosures(root = document, { openMs = 360, closeMs = 280 } = {}) {
+  root.querySelectorAll('details').forEach(details => {
+    const summary = details.querySelector(':scope > summary')
+    const content = summary?.nextElementSibling
+    if (!summary || !content || details.dataset.disclosureReady !== undefined) return
+    details.dataset.disclosureReady = ''
+    details.dataset.state = details.open ? 'open' : 'closed'
+    if (!content.animate) return
+    let animation = null
+    let opening = details.open
+    const values = () => {
+      const style = getComputedStyle(content)
+      return Object.fromEntries(PROPERTIES.map(property => [property, style[property]]))
+    }
+    const clear = () => { content.style.overflow = ''; content.style.boxSizing = '' }
+    summary.addEventListener('click', event => {
+      event.preventDefault()
+      if (!animation) opening = details.open
+      opening = !opening
+      details.dataset.state = opening ? 'open' : 'closed'
+      if (!opening && content.contains(document.activeElement)) summary.focus()
+      const current = animation ? values() : null
+      animation?.cancel()
+      animation = null
+      if (!animationAllowed()) { details.open = opening; clear(); return }
+      details.open = true
+      content.style.overflow = 'hidden'
+      content.style.boxSizing = 'border-box'
+      const expanded = values()
+      const collapsed = Object.fromEntries(PROPERTIES.map(property => [property, property === 'opacity' ? '0' : '0px']))
+      animation = content.animate([current || (opening ? collapsed : expanded), opening ? expanded : collapsed], {
+        duration: opening ? openMs : closeMs,
+        easing: opening ? 'cubic-bezier(.22, 1, .36, 1)' : 'cubic-bezier(.4, 0, 1, 1)',
+        fill: 'both',
+      })
+      animation.onfinish = () => { details.open = opening; animation.cancel(); animation = null; clear() }
+    })
+    details.addEventListener('toggle', () => { if (!animation) details.dataset.state = details.open ? 'open' : 'closed' })
+  })
+}

package/src/ui/primitives/index.mjs

@@ -0,0 +1,7 @@
+/**
+ * Atelier UI primitives (Node-safe): pure state, styles and markup
+ * helpers. Browser enhancers live in ./browser.mjs (@mnstry/atelier/ui/primitives/browser).
+ */
+export * from './state.mjs'
+export { carouselStyles } from './styles.mjs'
+export { renderCarouselControls } from './render.mjs'

package/src/ui/primitives/motion.mjs

@@ -0,0 +1,50 @@
+/**
+ * One owner for motion (browser): the reduced-motion preference and hidden tabs
+ * stop every effect started through these helpers.
+ */
+import { motionAllowed } from './state.mjs'
+
+const listeners = new Set()
+const running = new Set()
+let reduced = null
+let started = false
+
+function preference() {
+  if (!reduced && typeof matchMedia === 'function') reduced = matchMedia('(prefers-reduced-motion: reduce)')
+  return reduced
+}
+
+/** True when animation may run now. */
+export function animationAllowed() {
+  return motionAllowed(Boolean(preference()?.matches), false, typeof document !== 'undefined' && document.hidden)
+}
+
+/** Call `listener` whenever the motion preference or tab visibility changes. */
+export function onMotionChange(listener) {
+  listeners.add(listener)
+  startMotionWatch()
+  return () => listeners.delete(listener)
+}
+
+/** A Web Animation owned by the motion layer: skipped when motion is off, finished when it turns off. */
+export function animate(element, frames, options) {
+  if (!animationAllowed() || !element.animate) return null
+  const animation = element.animate(frames, options)
+  running.add(animation)
+  animation.finished.catch(() => {}).finally(() => running.delete(animation))
+  return animation
+}
+
+function sync() {
+  document.documentElement.classList.toggle('motion-paused', Boolean(preference()?.matches))
+  if (!animationAllowed()) running.forEach(animation => animation.finish())
+  listeners.forEach(listener => listener())
+}
+
+export function startMotionWatch() {
+  if (started || typeof document === 'undefined') return
+  started = true
+  preference()?.addEventListener('change', sync)
+  document.addEventListener('visibilitychange', sync)
+  sync()
+}

package/src/ui/primitives/render.mjs

@@ -0,0 +1,22 @@
+/** HTML for the carousel controls and live status (tenant-neutral, escaped). */
+const escape = value => String(value ?? '').replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[character]))
+const chevron = direction => `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="${direction === 'previous' ? 'M15 5l-7 7 7 7' : 'M9 5l7 7-7 7'}"/></svg>`
+const toggleIcons = '<svg class="system-carousel__pause" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><rect x="6" y="5" width="4" height="14"/><rect x="14" y="5" width="4" height="14"/></svg><svg class="system-carousel__play" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M7 5l12 7-12 7z"/></svg>'
+
+/**
+ * Controls for a carousel: optional scroll bar, optional autoplay toggle,
+ * previous and next buttons, and a polite status for reader-initiated moves.
+ */
+export function renderCarouselControls({ label = 'Carousel', autoplay = 'off', scrollbar = true, arrows = true } = {}) {
+  const name = escape(label)
+  const parts = []
+  if (scrollbar) parts.push('<div class="system-carousel__scrollbar" data-scrollbar aria-hidden="true"><span></span></div>')
+  const buttons = []
+  if (autoplay === 'discrete' || autoplay === 'smooth') buttons.push(`<button type="button" class="system-carousel__button system-carousel__toggle" data-autoplay-toggle aria-label="Pause automatic scrolling" hidden>${toggleIcons}</button>`)
+  if (arrows) {
+    buttons.push(`<button type="button" class="system-carousel__button" data-prev aria-label="Previous: ${name}">${chevron('previous')}</button>`)
+    buttons.push(`<button type="button" class="system-carousel__button" data-next aria-label="Next: ${name}">${chevron('next')}</button>`)
+  }
+  if (buttons.length) parts.push(`<div class="system-carousel__buttons">${buttons.join('')}</div>`)
+  return `<div class="system-carousel__controls" data-controls hidden>${parts.join('')}</div><p class="system-carousel__status" data-status aria-live="polite"></p>`
+}

package/src/ui/primitives/scroll-lock.mjs

@@ -0,0 +1,47 @@
+/**
+ * Layout-stable page scroll lock (browser), the contract documented in
+ * portable-presentation.md: measure the scrollbar a lock hides, pay it back as
+ * body end padding, expose it as --scroll-lock-gap for fixed and sticky
+ * elements, and restore both when the last lock is released. Locks are
+ * counted, so one closing overlay cannot release another's.
+ */
+import { scrollLockGap } from './state.mjs'
+
+const holders = new Set()
+let saved = null
+
+/** Lock page scrolling for `owner` (any value). Returns a release function. */
+export function lockScroll(owner = Symbol('scroll-lock')) {
+  holders.add(owner)
+  if (!saved) {
+    const html = document.documentElement
+    const body = document.body
+    // Measure the body's laid-out width, not the root's clientWidth: with a stable
+    // scrollbar gutter some engines report the root inconsistently during the change.
+    const before = body.getBoundingClientRect().width
+    saved = { padding: body.style.paddingInlineEnd, overflow: html.style.overflow, overscroll: html.style.overscrollBehavior }
+    html.style.overflow = 'hidden'
+    html.style.overscrollBehavior = 'none'
+    const gap = scrollLockGap(before, body.getBoundingClientRect().width)
+    const existing = parseFloat(getComputedStyle(body).paddingInlineEnd) || 0
+    if (gap) body.style.paddingInlineEnd = `${existing + gap}px`
+    html.style.setProperty('--scroll-lock-gap', `${gap}px`)
+    html.dataset.scrollLocked = ''
+  }
+  return () => unlockScroll(owner)
+}
+
+/** Release `owner`'s lock; the page unlocks when no holder remains. */
+export function unlockScroll(owner) {
+  holders.delete(owner)
+  if (holders.size || !saved) return
+  const html = document.documentElement
+  document.body.style.paddingInlineEnd = saved.padding
+  html.style.overflow = saved.overflow
+  html.style.overscrollBehavior = saved.overscroll
+  html.style.removeProperty('--scroll-lock-gap')
+  delete html.dataset.scrollLocked
+  saved = null
+}
+
+export const scrollLocked = () => holders.size > 0

package/src/ui/primitives/state.mjs

@@ -0,0 +1,130 @@
+/**
+ * Pure state for Atelier UI primitives. No DOM access, so every rule
+ * here is testable in Node and shared by the browser enhancers.
+ */
+
+/** Visible window of a carousel at `index`, with arrow availability. */
+export function slideWindow(index, length, visible, loop = false) {
+  const count = Math.max(1, Math.min(visible, length))
+  const max = Math.max(0, length - count)
+  const start = loop ? ((index % length) + length) % length : Math.min(max, Math.max(0, index))
+  return { start, end: Math.min(length, start + count), previousDisabled: !loop && start === 0, nextDisabled: !loop && start === max }
+}
+
+/** A horizontal intent must clearly dominate before the page scroll is taken over. */
+export function dragIntent(dx, dy) {
+  if (Math.abs(dx) < 8 && Math.abs(dy) < 8) return 'pending'
+  return Math.abs(dx) > Math.abs(dy) * 1.2 ? 'horizontal' : 'vertical'
+}
+
+/** Release decides the step: enough distance, or a quick flick. */
+export function swipeStep(dx, dy, elapsed = Infinity) {
+  if (Math.abs(dx) <= Math.abs(dy) * 1.2) return 0
+  const flick = elapsed < 300 && Math.abs(dx) >= 24
+  return Math.abs(dx) >= 50 || flick ? (dx < 0 ? 1 : -1) : 0
+}
+
+/** Motion runs only when the reader allows it, nothing paused it and the tab is visible. */
+export function motionAllowed(reduced, paused, hidden = false) {
+  return !reduced && !paused && !hidden
+}
+
+/** Clone sets needed on each side of a looping track to cover `perSide` slides. */
+export function loopSets(length, perSide) {
+  return Math.max(1, Math.ceil(perSide / Math.max(1, length)))
+}
+
+/** The index of the real slide showing the same content as item `index` of a looping track. */
+export function homeIndex(index, length, sets) {
+  return sets * length + ((index % length) + length) % length
+}
+
+/** Shortest signed distance from item `from` to any copy of real slide `to` in a loop. */
+export function nearestCopy(from, to, length) {
+  let delta = ((to - from) % length + length) % length
+  if (delta > length / 2) delta -= length
+  return delta
+}
+
+/** How far a slide has receded: 0 when it is the current slide, 1 from a full step away. */
+export function recede(position, index) {
+  return Math.min(1, Math.abs(position - index))
+}
+
+/** Few cards: when every card fits side by side (no narrower than `min`), show a still row. */
+export function rowFit(length, natural, gap, room, min) {
+  const width = Math.min(natural, (room - gap * (length - 1)) / length)
+  return width >= min ? Math.floor(width) : 0
+}
+
+/** Whole items that fit in the viewport: the size of one page for page-stepping carousels. */
+export function pageSize(viewport, step) {
+  return step > 0 ? Math.max(1, Math.floor((viewport + 1) / step)) : 1
+}
+
+/** Arrow step for page-stepping carousels. A loop only slightly longer than a page steps by the hidden remainder, so Next never reads as going backwards. */
+export function arrowStep(page, length, loop) {
+  if (!loop) return Math.max(1, page)
+  return Math.max(1, Math.min(page, length - page))
+}
+
+/** Wrap a position into [0, period). */
+export function wrap(position, period) {
+  if (!(period > 0)) return position
+  return ((position % period) + period) % period
+}
+
+/** Scroll position for a pointer on a scroll bar; `grab` is where the thumb was taken hold of. */
+export function scrubPosition(pointerX, railLeft, railWidth, thumbWidth, grab, range) {
+  const travel = railWidth - thumbWidth
+  if (travel <= 0 || range <= 0) return 0
+  const ratio = Math.min(1, Math.max(0, (pointerX - railLeft - grab) / travel))
+  return ratio * range
+}
+
+/** Scroll bar thumb geometry, as fractions of the rail, for a viewport over a content range. */
+export function thumbGeometry(position, range, viewport) {
+  const total = range + viewport
+  if (total <= 0) return { width: 1, left: 0 }
+  const width = Math.min(1, viewport / total)
+  const left = Math.min(Math.max(0, position), range) / total
+  return { width, left }
+}
+
+/** Momentum after a mouse drag: velocity in px/ms, decaying per 16ms frame. */
+export const MAX_GLIDE_VELOCITY = 2.5
+/** Release velocity in px/ms, capped so a fast fling travels a few cards, not the whole strip. */
+export function releaseVelocity(dx, dt) {
+  const velocity = -dx / Math.max(1, dt)
+  return Math.max(-MAX_GLIDE_VELOCITY, Math.min(MAX_GLIDE_VELOCITY, velocity))
+}
+export function glideStep(position, velocity, elapsed, friction = 0.94) {
+  const dt = Math.min(32, Math.max(0, elapsed))
+  return { position: position + velocity * dt, velocity: velocity * Math.pow(friction, dt / 16) }
+}
+
+/** Autoplay modes: a discrete step every interval, or a smooth drift in px/s. */
+export const AUTOPLAY_MODES = Object.freeze(['off', 'discrete', 'smooth'])
+export function autoplayConfig({ mode = 'off', interval = 6000, speed = 28 } = {}) {
+  return {
+    mode: AUTOPLAY_MODES.includes(mode) ? mode : 'off',
+    interval: Math.max(2500, Number(interval) || 6000),
+    speed: Math.min(400, Math.max(4, Number(speed) || 28)),
+  }
+}
+
+/** Advance a smooth drift; loops within `period` when one is given. */
+export function driftStep(position, speed, elapsed, period = 0, max = Infinity) {
+  const next = position + speed * Math.min(64, Math.max(0, elapsed)) / 1000
+  if (period > 0) return wrap(next, period)
+  return next >= max ? 0 : next
+}
+
+/**
+ * Scroll lock (portable-presentation contract): the width a lock must pay back
+ * is the scrollbar it hides, measured as the growth of the body's laid-out width.
+ * It is zero for overlay scrollbars and for gutters the browser keeps.
+ */
+export function scrollLockGap(widthBefore, widthAfter) {
+  return Math.max(0, Math.round((widthAfter - widthBefore) * 100) / 100)
+}

package/src/ui/primitives/styles.mjs

@@ -0,0 +1,127 @@
+/**
+ * Tenant-neutral carousel geometry and interaction styles. Tenants theme only
+ * through the --system-carousel-* custom properties; markup contract in
+ * docs/reference/ui-primitives.md.
+ */
+export const carouselStyles = `
+.system-carousel { position: relative; }
+.system-carousel [data-carousel-viewport] {
+  overflow-x: auto;
+  overscroll-behavior-inline: contain;
+  scroll-snap-type: x mandatory;
+  scroll-padding-inline: var(--system-carousel-inset, 0px);
+  scrollbar-width: none;
+}
+.system-carousel [data-carousel-viewport]::-webkit-scrollbar { display: none; }
+.system-carousel [data-carousel-track] {
+  display: flex;
+  gap: var(--system-carousel-gap, 1.25rem);
+  padding-inline: var(--system-carousel-inset, 0px);
+}
+.system-carousel [data-carousel-track] > * {
+  flex: 0 0 var(--system-carousel-slide, 100%);
+  min-width: 0;
+  scroll-snap-align: var(--system-carousel-align, start);
+}
+.system-carousel[data-peek] [data-carousel-track] > * { scroll-snap-align: center; }
+.system-carousel[data-drift] [data-carousel-viewport] { scroll-snap-type: none; }
+.system-carousel[data-fit="current"] [data-carousel-viewport] { transition: height 0.3s var(--system-carousel-ease, ease); }
+.system-carousel img { -webkit-user-drag: none; }
+@media (hover: hover) and (pointer: fine) {
+  .system-carousel[data-ready][data-overflow="true"] [data-carousel-viewport] { cursor: grab; }
+}
+.system-carousel[data-dragging] [data-carousel-viewport],
+.system-carousel[data-dragging] [data-carousel-viewport] * { cursor: grabbing; user-select: none; -webkit-user-select: none; }
+
+.system-carousel[data-peek] [data-carousel-track] > * {
+  transform: scale(calc(1 - var(--d, 0) * var(--system-carousel-recede-scale, 0.08)));
+  opacity: calc(1 - var(--d, 0) * var(--system-carousel-recede-fade, 0.35));
+}
+.system-carousel[data-row] [data-carousel-track] { justify-content: center; }
+.system-carousel[data-row] [data-carousel-track] > * { flex-basis: var(--slide-fit); transform: none; opacity: 1; }
+
+.system-carousel[data-carousel="fade"] [data-carousel-track] { display: grid; }
+.system-carousel[data-carousel="fade"] [data-carousel-track] > * {
+  grid-area: 1 / 1;
+  transition: opacity var(--system-carousel-fade-ms, 700ms) var(--system-carousel-ease, ease), visibility 0s linear var(--system-carousel-fade-ms, 700ms);
+}
+.system-carousel[data-carousel="fade"][data-ready] [data-carousel-track] > *:not(.is-current) { opacity: 0; visibility: hidden; }
+.system-carousel[data-carousel="fade"][data-ready] [data-carousel-track] > *.is-current { opacity: 1; visibility: visible; transition-delay: 0s; }
+
+.system-carousel__controls {
+  display: flex;
+  align-items: center;
+  justify-content: var(--system-carousel-controls-justify, center);
+  gap: var(--system-carousel-controls-gap, 1.25rem);
+  margin-top: var(--system-carousel-controls-offset, 1.5rem);
+}
+.system-carousel__controls[hidden], .system-carousel__controls [hidden] { display: none; }
+.system-carousel__buttons { display: flex; gap: 0.5rem; }
+.system-carousel__button {
+  display: grid;
+  place-items: center;
+  width: var(--system-carousel-button-size, 44px);
+  height: var(--system-carousel-button-size, 44px);
+  padding: 0;
+  border: 1px solid var(--system-carousel-button-border, currentColor);
+  border-radius: var(--system-carousel-button-radius, 0);
+  background: var(--system-carousel-button-background, transparent);
+  color: inherit;
+  cursor: pointer;
+  transition: background-color 0.24s var(--system-carousel-ease, ease), border-color 0.24s var(--system-carousel-ease, ease), opacity 0.24s var(--system-carousel-ease, ease);
+}
+.system-carousel__button:disabled { opacity: 0.32; cursor: default; }
+.system-carousel__button:active:not(:disabled) { transform: translateY(1px); }
+.system-carousel__button:focus-visible, .system-carousel__page:focus-visible {
+  outline: 2px solid var(--system-carousel-focus, currentColor);
+  outline-offset: 3px;
+}
+@media (hover: hover) and (pointer: fine) {
+  .system-carousel__button:not(:disabled):hover {
+    background: var(--system-carousel-button-hover-background, rgba(0, 0, 0, 0.06));
+    border-color: var(--system-carousel-button-hover-border, currentColor);
+  }
+}
+.system-carousel__toggle .system-carousel__play,
+.system-carousel__toggle[data-state="paused"] .system-carousel__pause { display: none; }
+.system-carousel__toggle[data-state="paused"] .system-carousel__play { display: block; }
+
+.system-carousel__scrollbar {
+  position: relative;
+  width: var(--system-carousel-scrollbar-width, min(260px, 38vw));
+  height: 28px;
+  overflow: hidden;
+  cursor: grab;
+  touch-action: none;
+}
+.system-carousel__scrollbar::before, .system-carousel__scrollbar > span {
+  content: '';
+  position: absolute;
+  top: 50%;
+  height: var(--system-carousel-scrollbar-thickness, 2px);
+  transform: translateY(-50%);
+}
+.system-carousel__scrollbar::before { left: 0; right: 0; background: var(--system-carousel-scrollbar-track, rgba(0, 0, 0, 0.14)); }
+.system-carousel__scrollbar > span { left: 0; width: 25%; background: var(--system-carousel-scrollbar-thumb, currentColor); transition: height 0.16s var(--system-carousel-ease, ease); }
+.system-carousel__scrollbar:hover > span, .system-carousel[data-scrubbing] .system-carousel__scrollbar > span { height: calc(var(--system-carousel-scrollbar-thickness, 2px) * 2); }
+.system-carousel[data-scrubbing] .system-carousel__scrollbar { cursor: grabbing; }
+
+.system-carousel__pages { display: flex; flex-wrap: wrap; justify-content: center; gap: 0.25rem; }
+.system-carousel__page { width: 24px; height: 24px; padding: 0; border: 0; background: none; cursor: pointer; display: grid; place-items: center; color: inherit; }
+.system-carousel__page::before { content: ''; width: 8px; height: 8px; border-radius: 50%; background: currentColor; opacity: 0.3; transition: opacity 0.24s var(--system-carousel-ease, ease); }
+.system-carousel__page[aria-current="true"]::before { opacity: 1; }
+.system-carousel__page[data-thumb] { width: var(--system-carousel-thumb-width, 72px); height: var(--system-carousel-thumb-height, 90px); opacity: 0.55; background: var(--thumb, none) center / cover; outline-offset: 2px; }
+.system-carousel__page[data-thumb]::before { content: none; }
+.system-carousel__page[data-thumb] img { width: 100%; height: 100%; object-fit: cover; }
+.system-carousel__page[data-thumb][aria-current="true"] { opacity: 1; box-shadow: 0 0 0 1px var(--system-carousel-thumb-current, currentColor); }
+.system-carousel__status {
+  position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden;
+  clip: rect(0 0 0 0); white-space: nowrap; border: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .system-carousel [data-carousel-track] > *, .system-carousel__button, .system-carousel__scrollbar > span,
+  .system-carousel[data-fit="current"] [data-carousel-viewport] { transition: none; }
+  .system-carousel[data-peek] [data-carousel-track] > * { transform: none; }
+}
+`

package/templates/external-project-workspace/pack-lifecycle.json

@@ -14,7 +14,8 @@
         "0.2.0-alpha.13",
         "0.2.0-alpha.14",
         "0.2.0-alpha.15",
-        "0.2.0-alpha.16"
+        "0.2.0-alpha.16",
+        "0.2.0-alpha.17"
       ],
       "status": "active"
     }