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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.0-alpha.18
+
+- Carousel autoplay keeps running under the pointer. It now holds for a press (any click, tap or drag), keyboard focus (not focus from a click), a wheel, an expanded slide, a hidden tab or the carousel being off screen, and resumes `data-resume` ms (default 2000) after the reader lets go; a smooth drift eases back to speed instead of jumping.
+- A thrown drifting strip coasts longer and stops where it stops: nothing pulls it back to a card or to its earlier resting place, and the loop renumbers invisibly over its clones while coasting. A scrub, or a slide brought to the centre, also stays put until an arrow or a drag moves it.
+- Opening a `<details>` inside a slide (a quick view, for example) brings that slide to the centre and holds autoplay until every expanded panel in the strip is closed.
+- In a loop, the scroll bar's end now shows the last slide at the viewport's inner end edge (measured, so side insets are respected), and the thumb wraps: as the strip drifts it leaves the right end and re-enters on the left. `renderCarouselControls` emits a second thumb segment for this; an enhancer adds it to older markup.
+- New pure helpers: `loopThumbGeometry`, `rampFactor`, `resumeDelay`.
+
+## 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 provides 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, plus 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 +328,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.18` refines carousel motion (gentle resume, coasting throws, centred expanded slides, a looping scroll bar). `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,20 @@ 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.18
+
+Carousel autoplay no longer holds on hover; it holds for a press, keyboard
+focus, a wheel or an expanded slide and resumes after `data-resume` ms. A site
+that relied on hover to pause autoplay should rely on the pause control. No
+stored record changes format.
+
+## 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,128 @@
+# 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 covers slideshows and multi-card strips: seamless loops, drag
+intent, focus safety, page dots and thumbnails, live status, height that follows
+the slide, receding neighbours, still rows, a draggable scroll bar, momentum,
+autoplay and 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 |
+| `data-resume` | ms, default 2000 | How long autoplay waits after the reader lets go before easing back in |
+
+### 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 keeps running under the
+  pointer, and holds for a press (any click, tap or drag), keyboard focus inside
+  the carousel, a wheel, an expanded slide, a hidden tab or the carousel being
+  off screen. It resumes `data-resume` ms after the reader lets go, and a smooth
+  drift eases back to speed over about a second. The rendered toggle pauses and
+  resumes it. `data-autoplay-state` reads `playing`, `held`, `paused` or `off`.
+- **Throws and resting places:** in a drifting strip, a thrown strip coasts to a
+  stop where it stops; nothing pulls it back to a card or to where it was. A
+  scrub, or a slide brought to the centre, also stays where the reader left it
+  until an arrow or a drag moves it again.
+- **Expanded slides:** opening a `<details>` inside a slide (a quick view, for
+  example) brings that slide to the centre and holds autoplay until every
+  expanded panel in the strip is closed again.
+- **Looping scroll bar:** in a loop the thumb is a window over one period. As the
+  strip drifts, the thumb leaves the right end and re-enters on the left.
+  Dragging the thumb to the right end shows the last slide at the right edge.
+- **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,9 @@
       "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",
+      "0.2.0-alpha.18"
     ],
     "packRefs": []
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnstry/atelier",
-  "version": "0.2.0-alpha.16",
+  "version": "0.2.0-alpha.18",
   "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'