Carousel

Carousel media CompositeControllerEndpointSprite

Ordered peer slides in a stable stage — media and/or HTML fragments; DOM-local prev/next/dots (clamp or loop); optional autoplay.

Layer: L2 host · Recipe: unset — see docs/agent/pick-a-surface.md. Curriculum: AGENTS.md; pick matrix: docs/agent/pick-a-surface.md; blast radius: CONSUMER_MAP.md.

Clamp — ends disable. Media fills the stage (object-fit: cover); chips name the source aspect. Last slide is a hero overlay (hypermedia in the same visual language).

Source 16∶9 · cover

Source 3∶4 · cover

Source 1∶1 · cover

Hypermedia slide

Adopt Mochi

Same stage as media — CTA and live region ride the strip, not a separate admin card.

Slide 1 of 4

Loop + autoplay — data-carousel-wrap="loop" · data-carousel-interval="3000". Advances every 3s; pauses while the pointer is over this strip; off under prefers-reduced-motion (status says so).

Slide 1 of 3

Copy this

html

<div class="stack" data-gap="lg">
  <div>
    <p class="hm-demo-muted" style="margin:0 0 var(--space-sm);font-size:var(--text-xs)"><strong>Clamp</strong> — ends disable. Media fills the stage (<code>object-fit: cover</code>); chips name the source aspect. Last slide is a hero overlay (hypermedia in the same visual language).</p>
    <div class="carousel" data-carousel data-carousel-index="0" data-carousel-wrap="none" data-size="lg" aria-roledescription="carousel" aria-label="Cat gallery">
      <div class="carousel__viewport" data-ratio="16/9">
        <div class="carousel__track">
          <div class="carousel__slide carousel__slide--media" data-active>
            <div class="carousel__media"><img src="media/carousel/cat-wide.svg" width="640" height="360" alt="Landscape cat illustration"><span class="carousel__chip">Source 16∶9 · cover</span></div>
          </div>
          <div class="carousel__slide carousel__slide--media">
            <div class="carousel__media"><img src="media/carousel/cat-tall.svg" width="300" height="400" alt="Portrait cat illustration"><span class="carousel__chip">Source 3∶4 · cover</span></div>
          </div>
          <div class="carousel__slide carousel__slide--media">
            <div class="carousel__media"><img src="media/carousel/cat-square.svg" width="400" height="400" alt="Square cat illustration"><span class="carousel__chip">Source 1∶1 · cover</span></div>
          </div>
          <div class="carousel__slide carousel__slide--hero">
            <div class="carousel__media"><img src="media/carousel/cat-wide.svg" width="640" height="360" alt=""></div>
            <div class="carousel__hero">
              <p class="carousel__hero-kicker">Hypermedia slide</p>
              <p class="carousel__hero-title">Adopt Mochi</p>
              <p class="carousel__hero-text">Same stage as media — CTA and live region ride the strip, not a separate admin card.</p>
              <button type="button" class="button" data-variant="primary" hx-get="/mock/carousel/adopt" hx-target="#hm-carousel-adopt" hx-swap="innerHTML">Request visit</button>
              <div id="hm-carousel-adopt" class="carousel__hero-live" aria-live="polite"></div>
            </div>
          </div>
        </div>
      </div>
      <div class="carousel__controls">
        <button type="button" class="carousel__btn" data-carousel-prev aria-label="Previous slide" disabled>‹</button>
        <div class="carousel__dots" role="group" aria-label="Slides"><button type="button" class="carousel__dot" aria-current="true" aria-label="Slide 1, landscape"></button><button type="button" class="carousel__dot" aria-label="Slide 2, portrait"></button><button type="button" class="carousel__dot" aria-label="Slide 3, square"></button><button type="button" class="carousel__dot" aria-label="Slide 4, adopt call to action"></button></div>
        <button type="button" class="carousel__btn" data-carousel-next aria-label="Next slide">›</button>
      </div>
      <p class="carousel__status" data-carousel-status aria-live="polite">Slide 1 of 4</p>
    </div>
  </div>
  <div>
    <p class="hm-demo-muted" style="margin:0 0 var(--space-sm);font-size:var(--text-xs)"><strong>Loop + autoplay</strong> — <code>data-carousel-wrap="loop"</code> · <code>data-carousel-interval="3000"</code>. Advances every 3s; pauses while the pointer is over this strip; off under <code>prefers-reduced-motion</code> (status says so).</p>
    <div class="carousel" id="hm-carousel-ambient" data-carousel data-carousel-index="0" data-carousel-wrap="loop" data-carousel-interval="3000" data-size="lg" aria-roledescription="carousel" aria-label="Ambient cat loop">
      <div class="carousel__viewport" data-ratio="16/9">
        <div class="carousel__track">
          <div class="carousel__slide carousel__slide--media" data-active>
            <div class="carousel__media"><img src="media/carousel/cat-wide.svg" width="640" height="360" alt="Ambient slide 1, landscape cat"></div>
          </div>
          <div class="carousel__slide carousel__slide--media">
            <div class="carousel__media"><img src="media/carousel/cat-tall.svg" width="300" height="400" alt="Ambient slide 2, portrait cat"></div>
          </div>
          <div class="carousel__slide carousel__slide--media">
            <div class="carousel__media"><img src="media/carousel/cat-square.svg" width="400" height="400" alt="Ambient slide 3, square cat"></div>
          </div>
        </div>
      </div>
      <div class="carousel__controls">
        <button type="button" class="carousel__btn" data-carousel-prev aria-label="Previous ambient slide">‹</button>
        <div class="carousel__dots" role="group" aria-label="Ambient slides"><button type="button" class="carousel__dot" aria-current="true" aria-label="Ambient slide 1"></button><button type="button" class="carousel__dot" aria-label="Ambient slide 2"></button><button type="button" class="carousel__dot" aria-label="Ambient slide 3"></button></div>
        <button type="button" class="carousel__btn" data-carousel-next aria-label="Next ambient slide">›</button>
      </div>
      <p class="carousel__status" data-carousel-status aria-live="polite">Slide 1 of 3</p>
    </div>
  </div>
</div>

Server exchange

When the client affordance finishes (click, confirm, keystroke…), htmx issues this request. Your API must return the response fragment in the table — usually HTML, not JSON (unless the partial says otherwise). Dazzle often renders these routes from the app model; a standalone HTMX4 app implements them explicitly. The Envelope column is the exchange envelope (part of the Swap contract) — what the response may re-emit relative to the persistent slot.

Do not reimplement the gallery. Flash toasts (e.g. “Deleted (demo).”), /mock/* paths, and other static-site scaffolding are demo-only (MOCK_HTMX in site/build_site.py). They are not Hyperpart surface and not a product API. If an agent is stuck “making the toast work,” stop — implement the exchange row below instead.

Request	Trigger	Response fragment	Swap	Envelope	States
`GET` `/app/adoptions/request`	Request visit CTA inside a rich (non-media) slide	confirmation fragment into the slide live region (badge / status line) — not a full strip re-render	#hm-carousel-adopt innerHTML (gallery) / live region in the slide	`body_only`	`populated` `error`

`GET` `/app/adoptions/request` — example handler

HTMX4 / standalone HM: return HTML fragments. Dazzle often emits this for you from the model; agents building a plain FastAPI app should match this shape. Not a dual-lock module — application code. Not a gallery mock. Respect exchange envelope body_only on the response.

python

@app.get("/app/adoptions/request")
async def adoption_request():
    return HTMLResponse('<span class="badge" data-tone="success">Visit requested</span>')

Swap contract

Agent-visible HTMX topology (ADR-0054 / decision 0012). exchange envelope = what the response may re-emit relative to the persistent slot (body_only | outer | none | host_owned | document). dual-lock validates part markup only — not this envelope. Stem: stems/morph-safe-hypermedia.md; decision: docs/decisions/0012-swap-identity-contract.md.

Gallery mocks may approximate morph with innerHTML — production follows the Swap + Envelope columns in Server exchange.

Exchanges (swap · envelope)

GET /app/adoptions/request → #hm-carousel-adopt innerHTML (gallery) / live region in the slide · envelope=body_only

Envelope rules

body_only — innerHTML / innerMorph into a slot; response is interior only (no re-wrap of slot id / nested data-dz-region).
outer — outerHTML / outerMorph; response may carry identity.
none — no HTML swap (JSON/204/bytes; client or OOB companion).
host_owned — swap target/mode chosen by the host button’s hx-target / hx-swap.
document — full navigation / document load (not a fragment).
Slot owns stable id / domain keys; state in DOM, not Alpine.

Envelope response examples

What the server returns for each exchange on Carousel. Match the exchange envelope; dual-lock still applies to interior markup.

`GET` `/app/adoptions/request` · envelope=`body_only`

Correct response for body_only into #hm-carousel-adopt (innerHTML / innerMorph). Wrong: re-wrapping the slot.

Do — correct response body

html

<!-- envelope=body_only → live-region confirmation in the slide -->
<span class="dz-badge" data-dz-tone="success">Request sent</span>

Don’t — violates body_only

html

<!-- WRONG: whole carousel stage -->
<div class="dz-carousel" data-dz-carousel>
  <div class="dz-carousel__track">…</div>
</div>

How to use it

Seams

root [data-carousel] + data-carousel-index
wrap: data-carousel-wrap=none|loop (default none = clamp)
autoplay: data-carousel-interval=ms (absent = off; min 500)
stage: .carousel__viewport[data-ratio] (1/1, 4/3, 16/9, 21/9)
slides .carousel__slide with data-active on the visible one
media full-bleed cover by default; chips name source aspect
optional contain: .carousel__media--contain; cover frame: .carousel__media--cover + aspect-ratio
hero hypermedia: .carousel__slide--hero + .carousel__hero overlay
status: [data-carousel-status] (“Slide N of M · Autoplay …”)
prev / next / dots; keyboard when a control inside is focused
decision 0009 + stem pragmatic-gallery-aesthetics

Do / Don't

Do	Don't
update data-active + aria-current + disabled ends in the DOM	keep slide index only in a JS variable (orphaned on morph)
full-bleed cover media with source-aspect chips for gallery polish	leave uneven black bars that look like missing CSS
hero overlay for CTAs inside the same stage as media	orphan form/card that breaks the strip’s visual continuity
show autoplay state in status (on / paused / reduced motion)	silent timer that agents cannot observe

Pitfalls

do not ship prev/next without a controller or server re-render
do not loop by default — clamp is the honest task-UI default
do not pause autoplay with document-level mouseenter on children (timer never re-arms) — pause only on root pointerenter/leave
do not put tabindex=0 on autoplay roots unless required (focus-within kills ambient demos)
do not teach mixed media with large letterbox gutters that look broken — full-bleed cover + chips; contain only when letterbox is the lesson
do not drop a padded admin card into the stage as 'hypermedia' — use hero overlay language
dots use role=group, not tablist
in-slide hx-* needs its own Exchange

Keyboard / AT

aria-label on prev/next; aria-current on the active dot
aria-live status including autoplay state; aria-roledescription=carousel
ArrowLeft/Right when focus is on a control inside the root
autoplay pauses while pointer is over the strip; off under reduced motion
dot hit targets are 24×24

Related parts

aspect-ratio button card badge

DOM contract

What the emitted HTML must satisfy — the table is the required surface; Python under contracts/ is the package-internal dual-lock CI runs (tests/test_contracts.py), not an app route. Standalone HTMX4: implement the API so responses match this markup. Dazzle: the agent emits SSR that already satisfies it. Do not invent attrs outside these tables. For request/response wiring see Server exchange.

`contracts/carousel.py`

Required in the DOM: root [data-carousel] (part carousel). Emit only these attributes — inventing extras is fine only if controllers ignore them; omitting required ones fails CI (tests/test_contracts.py).

Node	Attr	Constraint
`[data-carousel]`	`—`	—
`[data-carousel-index]`	`data-carousel-index`	present (any value)
`[data-carousel-prev]`	`—`	—
`[data-carousel-next]`	`—`	—
`[data-active]`	`—`	—
`[data-carousel-wrap]`	`data-carousel-wrap`	present (any value)
`[data-carousel-interval]`	`data-carousel-interval`	present (any value)
`[data-carousel-status]`	`—`	—

Module source

Import path is monorepo/package-local (from contracts._kit import …). Source-token form often uses data-*; gallery demos above are unprefixed. Do not copy this into app routes.

python

"""HYPERPART: carousel — slide strip with prev/next/dots (DOM-local state).

See docs/decisions/0009-carousel-stage-and-motion.md for wrap / autoplay / stage.
"""

from contracts._kit import DomContract, Node, Present

DOM_CONTRACT = DomContract(
    part="carousel",
    root="[data-dz-carousel]",
    nodes=(
        Node("[data-dz-carousel]", attrs={}),
        Node("[data-dz-carousel-index]", attrs={"data-dz-carousel-index": Present()}),
        Node("[data-dz-carousel-prev]", attrs={}),
        Node("[data-dz-carousel-next]", attrs={}),
        Node("[data-dz-active]", attrs={}),
        # Optional chrome / policy (present when authored)
        Node("[data-dz-carousel-wrap]", attrs={"data-dz-carousel-wrap": Present()}),
        Node("[data-dz-carousel-interval]", attrs={"data-dz-carousel-interval": Present()}),
        Node("[data-dz-carousel-status]", attrs={}),
    ),
)

__all__ = ["DOM_CONTRACT"]

Notes

Decision docs/decisions/0009-carousel-stage-and-motion.md. Only [data-active] slides show. Clamp (default) disables ends; data-carousel-wrap="loop" cycles. Autoplay via data-carousel-interval (pause on hover/focus; off under reduced motion). Stage: viewport data-ratio; media contain by default; cover via composed aspect-ratio. Hypermedia: slides are fragments; in-slide hx-* declares its own Exchange. shadcn/Embla parity job with DOM-carried state (HMC-037).

Source files

One logical Hyperpart, 4 code items (CSS layered, JS bundled). Bound by HYPERPART: carousel — python tools/hyperpart.py carousel lists them.

site/registry.py · contracts/carousel.py · components/carousel.css:1 · controllers/dz-carousel.js

Composed of

Aspect ratio · Button · Card

Carousel media CompositeControllerEndpointSprite

Copy this

Server exchange

GET /app/adoptions/request — example handler

Swap contract

Exchanges (swap · envelope)

Envelope rules

Envelope response examples

GET /app/adoptions/request · envelope=body_only

How to use it

Seams

Do / Don't

Pitfalls

Keyboard / AT

Related parts

DOM contract

contracts/carousel.py

Module source

Notes

Source files

Composed of

`GET` `/app/adoptions/request` — example handler

`GET` `/app/adoptions/request` · envelope=`body_only`

`contracts/carousel.py`