contour-deck 0.0.0-stage → 0.2.0

package/docs/CONTRACT.md

@@ -0,0 +1,178 @@
+# HTML contract
+
+This is the HTML that `contour-deck/rehype` (or any other producer) writes and that the core reads.
+The core recognises `data-ct-*` attributes only, never tag or class names, so page content may hold any HTML, including its own `<section>` elements.
+A change to this file goes in its own commit whose message starts with `contract:`.
+
+## Example
+
+```html
+<div data-ct-deck data-title="大綱優先的簡報">
+  <section data-ct-block data-title="三、翻頁怎麼運作" data-short="三" data-minutes="5">
+    <section data-ct-slide id="s-4-6" data-title="長頁怎麼停靠？" data-legacy="11" data-legacy-v="0">
+      <section data-ct-page data-ms="9800">
+        <h2>長頁怎麼停靠？</h2>
+        <ul>
+          <li data-ct-step data-ms="2300">…</li>
+          <li data-ct-step data-ms="1900">…</li>
+        </ul>
+        <aside data-ct-notes><p>…講稿…</p></aside>
+      </section>
+      <section data-ct-page>…</section>
+    </section>
+  </section>
+  <section data-ct-block data-kind="appendix" data-title="附錄 A｜結構與命名" data-short="A">
+    …
+  </section>
+</div>
+```
+
+## Nesting
+
+```text
+[data-ct-deck]          exactly one per deck
+  [data-ct-block]       1 or more, element children of the deck
+    [data-ct-slide]     1 or more, element children of a block
+      [data-ct-page]    1 or more, element children of a slide
+        content         any HTML
+        [data-ct-step]  0 or more, anywhere inside the page content
+        [data-ct-notes] 0 or more, element children of the page
+```
+
+- Each level holds only the level below it: a deck has no element child other than blocks, a block none other than slides, a slide none other than pages.
+  Anything that belongs to the document but not to a slide (footnotes, ESM nodes) stays outside the deck element.
+- A deck, block, slide, or page never appears inside page content, and decks do not nest.
+- A deck without block markers still has one block that wraps every slide.
+- Source order is presentation order at every level.
+- Tag names are free. `section` is recommended for block, slide, and page, and `aside` for notes, so the page reads as a document without JavaScript.
+
+## Attributes the producer writes
+
+| Element | Attribute | Required | Value |
+| --- | --- | --- | --- |
+| deck | `data-ct-deck` | yes | no value |
+| deck | `data-title` | no | Deck title as plain text, shown in the bar over the outline. Default: `document.title`. |
+| block | `data-ct-block` | yes | no value |
+| block | `data-title` | yes | Block title as plain text, for example `三、翻頁怎麼運作`. A deck with one unnamed block uses the deck title. |
+| block | `data-short` | no | Label of at most 3 characters for the locator rail and thumbnail numbers, for example `三`. Default: the block's 1-based ordinal. |
+| block | `data-minutes` | no | Planned minutes, a positive number (`5`, `1.5`). Omit when unknown. |
+| block | `data-kind` | no | One token. The core knows `appendix`; any other value is carried but has no behaviour. |
+| slide | `data-ct-slide` | yes | no value |
+| slide | `data-title` | yes | Slide title as plain text: its first heading, or a fallback the producer chooses. |
+| slide | `id` | yes | Unique in the document. The author's id when given, otherwise `s-<b>-<s>` with the 1-based block and slide ordinals. |
+| slide | `data-legacy` | no | The slide's old reveal.js horizontal index: the 0-based `h` of `?view=slides&slide=h.v`. Several slides split from one old vertical stack share it. |
+| slide | `data-legacy-v` | no | The old 0-based `v` of the slide's first page; page `k` (0-based) of the slide was old `h.(v+k)`. Absent means `0`. |
+| page | `data-ct-page` | yes | no value |
+| page | `data-ms` | no | Reading time of the page without its steps, in whole milliseconds (autoplay). |
+| step | `data-ct-step` | yes | no value |
+| step | `data-ms` | no | Reading time of the step, in whole milliseconds (autoplay). |
+| notes | `data-ct-notes` | yes | no value |
+| content | `data-ct-sk` | no | Thumbnail hint on an element child of a page: `text`, `list`, `table`, `grid`, `flow`, `nums`, `quote`, or `figure`. See [Thumbnails](#thumbnails). |
+
+`data-title`, `data-short`, `data-minutes`, `data-kind`, `data-legacy`, `data-legacy-v`, and `data-ms` have meaning only on the elements listed here.
+
+### Blocks
+
+- `::block{title="…" minutes=5 kind=appendix}` starts a block and supplies `data-title`, `data-minutes`, and `data-kind`.
+- Without `::block`, a slide that opens with a kicker heading (`####`) starts a block whose title is the heading text.
+- With neither, the whole deck is one block.
+- `data-kind="appendix"` marks a block the linear advance never enters: it is reached from the outline, the locator rail, or a deep link.
+
+### Steps
+
+- Every child a `:::build` reveals one at a time carries `data-ct-step`: list items, table body rows, or other blocks, by the rule `rehype-slides.ts` uses for fragments.
+- The reveal order is document order within the page.
+- A step is never inside `[data-ct-notes]`.
+- Without JavaScript every step is visible.
+
+### Notes
+
+- `:::summary` becomes `<aside data-ct-notes>` in the page where it was written.
+- A page with several notes elements reads them in document order.
+- The stylesheet hides notes in the document and on the stage; the notes panel and the notes view show their HTML.
+
+### Thumbnails
+
+The outline draws a schematic of each slide's first page from the first two content elements (element children of the page that are not notes and not `h1`–`h6`).
+The type of each comes from `data-ct-sk` when present, otherwise from the element itself:
+
+| Type | Detected without a hint |
+| --- | --- |
+| `list` | `ul`, `ol` |
+| `table` | `table`, or an element whose only element child is a `table` |
+| `quote` | `blockquote` |
+| `figure` | `figure`, `img`, `picture`, `svg`, `canvas`, `video`, `iframe` |
+| `grid` | a `div` with two or more element children |
+| `text` | anything else |
+
+`flow` and `nums` are drawn only from a hint.
+
+## What the core adds at run time
+
+The producer never writes these.
+The core removes all of them in `destroy()`.
+
+| Name | On | Meaning |
+| --- | --- | --- |
+| `data-ct-on` | step | The step is revealed. |
+| `data-ct-active` | block | The block is the one on the stage. |
+| `data-ct-current` | page | The page is the current one on the stage. It replaces reveal.js `.present` as the hook for entrance animations (`--i`). |
+| `data-ct-open` | `<html>` | A deck is open. The stylesheet uses it to stop the document behind from scrolling. |
+| `class="ct-…"` | elements the core creates | The app shell around the deck. The core adds no class to contract elements. |
+
+Every other `data-ct-*` name is reserved for later versions, except the [host attributes](#host-attributes).
+
+`contour-deck/remote`, when it loads, adds one `<style data-ct-remote>` at the start of `<head>` and leaves it there; its elements (`.ct-rp`, `.ct-laser`, `.ct-ink`, and the `.ct-app` of the phone and presenter views) go with the session or the view that made them.
+
+The core moves the deck element into its shell (`.ct-app .ct-stage`) while the deck is open and puts it back in `destroy()`; it does not clone it.
+The shell is inserted where the deck element was, so the deck keeps its ancestors and the styles it inherits from them.
+
+### Events on page elements
+
+| Event | When | `detail` |
+| --- | --- | --- |
+| `ct:enter` | The page becomes the current page on the stage. | `{ block, slide, page }`, 1-based |
+| `ct:leave` | The page stops being current: another page, the outline, or `destroy()`. | same |
+
+Both bubble, so a listener on the deck or the document sees them.
+
+## Host attributes
+
+`contour-deck/host` (the script `Deck.astro` runs) reads these from the host page.
+The core does not read them, and a host that calls `createDeck` itself needs none.
+
+| Attribute | On | Meaning |
+| --- | --- | --- |
+| `data-ct-host` | the wrapper of one deck element | The element the host script mounts. The deck may sit at any depth inside it. |
+| `data-ct-doc-class` | the wrapper | Space-separated classes the wrapper carries only while the deck is closed; the script removes them on opening and restores them on closing. |
+| `data-ct-paging` | the wrapper | `snap` or `free`: the `paging` option of the core. |
+| `data-ct-overview` | the wrapper | `flat` or `3d`: the `overview` option of the core. |
+| `data-ct-legacy` | the wrapper | Accept old reveal.js links: `?view=slides&slide=h.v` is rewritten to `?view=deck&at=…` through `data-legacy` and `data-legacy-v`. |
+| `data-ct-start` | any control in the page | A click opens the deck; with the value `notes`, its notes view. Inside a wrapper it opens that deck, elsewhere the first deck of the page. |
+| `data-ct-remote` | the wrapper | The deck has the remote button and the `R` key (`contour-deck/remote`, loaded on first use). |
+| `data-ct-relay` | the wrapper | Base URL of the relay (`wss://…`) for the phone remote; implies `data-ct-remote`. See [PROTOCOL.md](PROTOCOL.md). |
+
+## Deep links
+
+The core owns two query parameters while a deck is open, and removes both in `destroy()`.
+
+| Parameter | Value | Meaning |
+| --- | --- | --- |
+| `view` | `deck` | The deck is open. The host decides from this parameter whether to call `createDeck`. |
+| `view` | `notes` | The deck is open in the notes view (speaker notes as a scrolling script). |
+| `at` | `b.s` or `b.s.p` | 1-based ordinals: block in the deck, slide in the block, page in the slide. `4.4.2` is the second page of the fourth slide of the fourth block. |
+| `at` | an element id | The slide, page, or block with that id, or the one that contains the element with that id. |
+
+`contour-deck/remote` owns two more values of `view`, on pages that are views of a deck open elsewhere; the host loads the module when it sees them.
+
+| Parameter | Value | Meaning |
+| --- | --- | --- |
+| `view` | `remote` | The phone remote of the first deck of the page. |
+| `view` | `presenter` | The presenter window, in the same browser as the deck. |
+| `room` | 26 characters of Crockford base32 | The room both sides meet in: the relay room of the phone, the `BroadcastChannel` of the presenter window. |
+
+The links to these views keep every other query parameter of the deck's page and drop `at` and the fragment.
+
+Without `at` the deck opens on the outline.
+The position is in the query string, not the fragment, because a restricted page on the blog drops the fragment on redirect.
+The slide `id` also works as a plain document anchor (`#s-4-6`) when the deck is closed.

package/docs/PROTOCOL.md

@@ -0,0 +1,99 @@
+# Remote protocol
+
+How a deck (the **host**) and phones (**guests**) talk through the relay. The relay is a per-room forwarder; it decides who may hold the host seat, and the host decides who may control the deck. Version 1.
+
+Version 1 changed before its first release (contour-deck 0.1.0 has no remote): the host seat needs a key, the relay removes a guest the host denied or revoked, it limits requests per client address, and `state` lost `block`. Nothing that spoke the earlier draft was published, so the version stays 1.
+
+## Transport
+
+```
+wss://<relay>/v1/room/<room>?role=host&key=<key>
+wss://<relay>/v1/room/<room>?role=guest
+```
+
+- `key`: the host key, 26 characters of Crockford base32 (128 random bits from `crypto.getRandomValues`). The host keeps it in `sessionStorage` and sends it to the relay only.
+- `room`: the first 26 characters of the Crockford base32 encoding of SHA-256 of the key (its UTF-8 bytes, upper case), bits taken most significant first. The QR and every link carry the room, never the key. Anything that is not 26 Crockford characters gets HTTP 400.
+- Test vector: key `0123456789ABCDEFGHJKMNPQRS` opens room `YQV9WCK1VFXD4486E3JKK6CYND`.
+- Frames are UTF-8 JSON text, at most **2048 bytes**. A larger or binary frame closes the socket with `1009`.
+- Every message has a string field `t` (its type). The relay reads only `t`, `to`, and the size; it never stores or logs message bodies.
+
+## Relay rules
+
+One Durable Object per room (`idFromName(room)`).
+
+| Event | Relay does |
+| --- | --- |
+| host opens without a key, or with a key whose room is not this room | HTTP 403 before the upgrade |
+| socket opens | sends `{ "t": "hello", "id": "<8 chars>", "role": "host" \| "guest" }` to it. `id` is assigned by the relay. |
+| host opens while a host is connected | the new host takes the seat: the old host is closed with `4009`, its guests with `4000`; the room stays |
+| guest opens with no host connected | closes it with `4004` |
+| guest opens when 4 guests are connected | closes it with `4029` |
+| guest opens / closes | sends `{ "t": "join", "id" }` / `{ "t": "leave", "id" }` to the host |
+| host sends a message with `to` | forwards it to that guest only (unknown `to` is dropped) |
+| host sends `deny` or `revoke` with `to` | forwards it, then closes that guest with `4003` (the guest leaves; the host gets `leave`) |
+| host sends a message without `to` | forwards it to every guest |
+| guest sends a message | forwards it to the host only, with `from` set to the guest's id (overwriting any `from` the guest sent) |
+| host closes | closes every guest with `4000`; the room is gone |
+| no message in the room for 2 hours | closes everyone with `4000` |
+| a socket exceeds 60 messages/s (burst 120) | extra messages are dropped; above 10 s of sustained excess, closes with `1008` |
+| request `Origin` not in `ALLOWED_ORIGINS` | HTTP 403 before the upgrade |
+| more than 60 requests to room paths a minute from one client address | HTTP 429 before anything else is checked |
+
+`ALLOWED_ORIGINS` is a comma-separated Worker variable (e.g. `https://www.wayneh.tw,https://wayne930242.github.io,http://localhost:4321`). Guests never reach other guests.
+
+Only the key holder can be host, so only the deck's own tab receives what guests send, the resume token included. A host that reconnects while the relay still counts its old connection as open takes the seat back at once. Of two tabs with the same key (a duplicated tab copies `sessionStorage`), the newer one holds the seat; the older one is closed with `4009` and does not reconnect by itself.
+
+`GET /v1/health` answers `200 ok` (no upgrade) for monitoring.
+
+## Application messages
+
+The relay does not interpret these, except that a `deny` or `revoke` with `to` removes that guest. Coordinates are normalised to the stage viewport: `x`, `y` in `[0, 1]`, origin at the top left.
+
+### Pairing
+
+1. Host opens the room with its key and shows a QR for `<page URL>?view=remote&room=<room>`.
+2. Guest connects; host gets `join` and sends `{ "t": "pair", "to": id, "code": "1234" }` — a fresh 4-digit code per guest.
+3. Guest shows the code large. Host shows "a phone asks for control: code 1234 — allow / deny".
+4. Presenter compares the two screens and answers:
+   - allow → `{ "t": "grant", "to": id, "token": "<22 chars>" }` (random, kept by the guest in `sessionStorage` for this room)
+   - deny → `{ "t": "deny", "to": id }`; the relay then closes that guest with `4003`, so a denied guest cannot keep a place
+5. A reconnecting guest sends `{ "t": "resume", "token" }`; if it matches a token the host granted in this room, the host grants again without asking.
+6. The host can take control back: `{ "t": "revoke", "to": id }`, which also removes the guest from the room (`4003`). At most one guest holds control; granting a second revokes the first.
+
+A guest that is not granted gets `state` messages only if the host chooses (default: none), and its commands are ignored. A projected QR scanned by the audience therefore only produces a request the presenter denies.
+
+### Host → granted guest
+
+| Message | Fields |
+| --- | --- |
+| `state` | `mode` (`overview` \| `stage`), `at` (`b.s.p`, 1-based), `step`, `steps`, `elapsed` (s), `total` (s or `null`), `blockElapsed` (s), `blockMinutes` (or `null`), `ratio` (optional: width over height of the stage) |
+
+Sent on every position change and every 15 s. No text of the page crosses the relay: the phone has the same page and reads the notes and the block title from its own DOM, at the position `at` names.
+
+### Granted guest → host
+
+| Message | Fields | Host does |
+| --- | --- | --- |
+| `cmd` | `c`: `next` \| `prev` \| `slideNext` \| `slidePrev` \| `pageNext` \| `pagePrev` \| `overview` \| `open`; `at` with `open` | same as the keyboard |
+| `ptr` | `x`, `y`, `on` (bool) | shows or hides the laser pointer |
+| `ink` | `s` (stroke id, number), `pts` ([x, y, x, y, …], at most 64 points), `end` (bool, optional) | draws the stroke on the overlay |
+| `ink-clear` | — | clears the overlay |
+| `ping` | — | answers `{ "t": "pong", "to": from }` |
+
+Ink is cleared when the page changes. The host rate-limits `ptr` rendering to one per animation frame.
+
+## Same machine
+
+The presenter window on the same computer uses `BroadcastChannel("contour-deck:<room>")` with the same messages, without `pair` (same browser, trusted).
+
+## Close codes
+
+| Code | Meaning |
+| --- | --- |
+| `4000` | room closed (host left or idle, or a new host took the seat) |
+| `4003` | removed by the host (after `deny` or `revoke`); the client does not reconnect by itself |
+| `4004` | no host in this room |
+| `4009` | host replaced: a newer connection with the same key holds the host seat; the client does not reconnect by itself |
+| `4029` | room full |
+| `1008` | rate limit |
+| `1009` | message too large |

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "contour-deck",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Outline-first slide decks on real DOM: blocks, slides, pages.",
+  "keywords": [
+    "slides",
+    "presentation",
+    "astro-component"
+  ],
+  "license": "MPL-2.0",
+  "author": "洪偉 <me@wayneh.tw>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wayne930242/contour-deck.git"
+  },
+  "homepage": "https://github.com/wayne930242/contour-deck#readme",
+  "bugs": {
+    "url": "https://github.com/wayne930242/contour-deck/issues"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
+    },
+    "./remark": {
+      "types": "./dist/remark/index.d.ts",
+      "default": "./dist/remark/index.js"
+    },
+    "./rehype": {
+      "types": "./dist/rehype/index.d.ts",
+      "default": "./dist/rehype/index.js"
+    },
+    "./remote": {
+      "types": "./dist/remote/index.d.ts",
+      "default": "./dist/remote/index.js"
+    },
+    "./astro": "./dist/astro/Deck.astro",
+    "./host": {
+      "types": "./dist/astro/host.d.ts",
+      "default": "./dist/astro/host.js"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "docs/CONTRACT.md",
+    "docs/PROTOCOL.md",
+    "styles"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:browser": "node scripts/build.mjs && playwright test --pass-with-no-tests",
+    "size": "node scripts/size.mjs",
+    "demo": "node scripts/build.mjs && node scripts/serve.mjs",
+    "fixtures": "node scripts/build.mjs && node scripts/fixtures.mjs",
+    "demo:decks": "node scripts/build.mjs && node scripts/demo-decks.mjs",
+    "media": "node scripts/build.mjs && node scripts/media.mjs"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.65.0",
+    "@types/node": "^26.6.6",
+    "esbuild": "0.28.2",
+    "jsqr": "1.4.0",
+    "rehype-stringify": "^10.0.1",
+    "remark-cjk-friendly": "^2.3.4",
+    "remark-directive": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "typescript": "7.0.2",
+    "unified": "^11.0.5",
+    "vfile": "^6.0.3",
+    "vite": "^8.3.8",
+    "vitest": "5.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "pnpm@12.9.1"
+}

package/styles/base.css

@@ -0,0 +1,3 @@
+/* Without the script the deck is a plain document; only the speaker notes are hidden. */
+[data-ct-notes] { display: none; }
+html[data-ct-open] { overflow: hidden; }

package/styles/deck.css

@@ -0,0 +1,151 @@
+/* The open deck. Theme: set the --ct-* of this first rule on .ct-app; the defaults follow the site's own variables. */
+:where(.ct-app) {
+  --ct-bg: var(--background, Canvas);
+  --ct-fg: var(--foreground, CanvasText);
+  --ct-accent: var(--accent, #e3311d);
+  --ct-accent-fg: var(--accent-foreground, #fff);
+  --ct-border: var(--border, color-mix(in srgb, var(--ct-fg) 24%, var(--ct-bg)));
+  --ct-muted: var(--muted-foreground, color-mix(in srgb, var(--ct-fg) 62%, var(--ct-bg)));
+  --ct-measure: 62rem;
+  --ct-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+}
+.ct-app {
+  --ct-panel: color-mix(in srgb, var(--ct-fg) 4%, var(--ct-bg));
+  --ct-tint: color-mix(in srgb, var(--ct-accent) 10%, var(--ct-bg));
+  --ct-ease: cubic-bezier(.22, 1, .36, 1);
+  --ct-notes-w: min(24rem, 38vw);
+  --ct-lift: 12px;
+  position: fixed; inset: 0; z-index: 1000;
+  display: grid; grid-template-rows: 3rem minmax(0, 1fr);
+  overflow: hidden; background: var(--ct-bg); color: var(--ct-fg); line-height: 1.5;
+}
+:where(.ct-app, .ct-app *) { box-sizing: border-box; }
+.ct-app :focus-visible { outline: 2px dashed var(--ct-accent); outline-offset: 2px; }
+.ct-app :is(.ct-open, .ct-thumb, .ct-rl, .ct-rc, .ct-sh) { font: inherit; color: inherit; background: none; border: 0; padding: 0; cursor: pointer; text-align: left; }
+.ct-live { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+.ct-meta { font: .66rem/1 var(--ct-mono); color: var(--ct-muted); white-space: nowrap; }
+.ct-badge { font: 650 .62rem/1 var(--ct-mono); letter-spacing: .1em; padding: .28rem .4rem; background: color-mix(in srgb, var(--ct-fg) 10%, var(--ct-bg)); color: var(--ct-muted); }
+
+/* ---- bar ---- */
+.ct-bar { display: flex; align-items: center; gap: .6rem; padding: 0 .7rem; min-width: 0; background: var(--ct-panel); }
+.ct-btn { font: 650 .68rem/1 var(--ct-mono); letter-spacing: .08em; padding: .5rem .6rem; border: 1px solid var(--ct-border); background: var(--ct-bg); color: inherit; cursor: pointer; white-space: nowrap; min-height: 2rem; }
+.ct-btn:hover { background: var(--ct-tint); }
+.ct-btn[aria-pressed="true"] { background: var(--ct-fg); color: var(--ct-bg); border-color: var(--ct-fg); }
+.ct-app[data-ct-mode="overview"] :is([data-ct-act="overview"], [data-ct-act="notes"]),
+.ct-app:not([data-ct-mode="overview"]) :is([data-ct-act="3d"], [data-ct-act="script"]),
+.ct-app[data-ct-mode="notes"] [data-ct-act="notes"] { display: none; }
+.ct-title { font-size: .8rem; font-weight: 700; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 16rem; }
+
+/* locator rail: one column per slide, one pip per page */
+.ct-rail { position: relative; flex: 1; min-width: 0; height: 100%; display: flex; align-items: flex-start; justify-content: center; gap: .7rem; padding-top: .55rem; overflow: hidden; }
+.ct-rg { display: flex; align-items: flex-start; gap: 3px; }
+.ct-app .ct-rl { font: 650 .62rem/11px var(--ct-mono); color: var(--ct-muted); padding-right: .2rem; }
+.ct-app .ct-rg[data-cur] .ct-rl { color: var(--ct-fg); }
+.ct-app .ct-rc { display: flex; flex-direction: column; gap: 2px; padding-bottom: 8px; }
+.ct-rc i { display: block; width: 12px; height: 5px; background: var(--ct-border); }
+.ct-rg[data-cur] i { background: var(--ct-muted); }
+.ct-rg[data-kind="appendix"] i { opacity: .55; }
+.ct-rm { position: absolute; left: 0; top: 0; width: 12px; height: 5px; background: var(--ct-accent); outline: 2px solid color-mix(in srgb, var(--ct-accent) 35%, transparent); pointer-events: none; transition: transform .34s var(--ct-ease); }
+
+.ct-vp { position: relative; overflow: hidden; perspective: 1700px; }
+
+/* ---- outline ---- */
+.ct-ov { position: absolute; inset: 0; overflow: auto; padding: 1.1rem; }
+.ct-plane { position: relative; display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 19rem), 1fr)); gap: 1rem; max-width: 86rem; margin: 0 auto; transform-style: preserve-3d; transition: transform .7s var(--ct-ease); }
+.ct-tile { border: 1px solid var(--ct-border); background: var(--ct-bg); padding: .7rem .8rem .9rem; transform-style: preserve-3d; min-width: 0; }
+.ct-tile[data-kind="appendix"] { background: var(--ct-panel); }
+@media (min-width: 900px) { .ct-tile[data-wide] { grid-column: span 2; } }
+.ct-app .ct-open { display: flex; align-items: baseline; gap: .5rem; width: 100%; padding: .1rem 0; }
+.ct-open:hover .ct-tt { text-decoration: underline; text-underline-offset: .2em; }
+.ct-tt { font-size: .95rem; font-weight: 800; }
+.ct-open .ct-meta { margin-left: auto; }
+.ct-strip { list-style: none; display: flex; flex-wrap: wrap; gap: 1.5rem .8rem; margin: .7rem 0 0; padding: 0; transform-style: preserve-3d; }
+.ct-strip li { transform-style: preserve-3d; margin: 0; }
+.ct-app .ct-thumb { position: relative; display: block; width: 7.6rem; aspect-ratio: 16 / 11; transform-style: preserve-3d; margin: 0 calc((var(--n) - 1) * 3px) calc((var(--n) - 1) * 3px) 0; transition: transform .25s var(--ct-ease); }
+.ct-layer, .ct-face { position: absolute; inset: 0; border: 1px solid var(--ct-border); background: var(--ct-bg); transition: transform .7s var(--ct-ease), background-color .2s; }
+.ct-layer { transform: translate(calc(var(--k) * 3px), calc(var(--k) * 3px)); }
+.ct-face { padding: .35rem .4rem; display: flex; flex-direction: column; gap: .2rem; overflow: hidden; }
+.ct-thumb:is(:hover, :focus-visible) .ct-face { background: var(--ct-tint); }
+.ct-app .ct-thumb:focus-visible { outline: none; }
+.ct-num { font: .56rem/1 var(--ct-mono); color: var(--ct-muted); display: flex; justify-content: space-between; }
+.ct-t { font-size: .64rem; line-height: 1.25; font-weight: 750; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+.ct-sk { margin-top: auto; display: flex; flex-direction: column; gap: 3px; }
+.ct-g { display: block; height: 7px; }
+.ct-g-text, .ct-g-list { width: 92%; background: repeating-linear-gradient(var(--ct-border) 0 2px, transparent 2px 5px); }
+.ct-g-list { width: 66%; margin-left: 6px; height: calc(var(--c) * 5px - 3px); }
+.ct-g-table { height: 13px; border: 1px solid var(--ct-border); background: linear-gradient(90deg, transparent 33%, var(--ct-border) 33% calc(33% + 1px), transparent 0 66%, var(--ct-border) 66% calc(66% + 1px), transparent 0), linear-gradient(transparent 6px, var(--ct-border) 6px 7px, transparent 0); }
+.ct-g-figure { height: 13px; width: 60%; border: 1px solid var(--ct-border); background: linear-gradient(to top right, transparent calc(50% - .5px), var(--ct-border) 0 calc(50% + .5px), transparent 0); }
+.ct-g-grid, .ct-g-flow, .ct-g-nums { display: flex; gap: 3px; height: 12px; }
+.ct-g-grid b, .ct-g-flow b { flex: 1; border: 1px solid var(--ct-border); }
+.ct-g-flow { gap: 6px; background: linear-gradient(var(--ct-border), var(--ct-border)) center / 100% 1px no-repeat; }
+.ct-g-flow b { background: var(--ct-bg); }
+.ct-g-nums b { width: 16px; background: color-mix(in srgb, var(--ct-accent) 55%, var(--ct-bg)); }
+.ct-g-quote { background: var(--ct-tint); height: 9px; }
+.ct-ring { position: absolute; left: 0; top: 0; pointer-events: none; outline: 2px solid var(--ct-accent); outline-offset: 3px; z-index: 3; transition: left .38s var(--ct-ease), top .38s var(--ct-ease), width .38s var(--ct-ease), height .38s var(--ct-ease), transform .7s var(--ct-ease); }
+.ct-ring::after { content: attr(data-label); position: absolute; left: -5px; top: calc(100% + 5px); font: 650 .56rem/1 var(--ct-mono); letter-spacing: .08em; padding: .2rem .3rem; background: var(--ct-accent); color: var(--ct-accent-fg); white-space: nowrap; }
+
+/* 3D structure: the plane tilts and every slide becomes a stack as high as its page count */
+.ct-app[data-ct-3d] .ct-ov { overflow: hidden; }
+.ct-app[data-ct-3d] .ct-plane { transform: translateY(-4%) rotateX(52deg) rotateZ(-24deg) scale(.86); }
+.ct-app[data-ct-3d] .ct-layer { transform: translateZ(calc((var(--n) - 1 - var(--k)) * var(--ct-lift))); }
+.ct-app[data-ct-3d] .ct-face { transform: translateZ(calc((var(--n) - 1) * var(--ct-lift))); }
+.ct-app[data-ct-3d] .ct-thumb:is(:hover, :focus-visible) { transform: translateZ(22px); }
+.ct-app[data-ct-3d] .ct-ring { transform: translateZ(calc((var(--n) - 1) * var(--ct-lift) + 1px)); }
+
+/* ---- stage: one block is a left-right track; each slide scrolls by pages ---- */
+.ct-stage { position: absolute; inset: 0; background: var(--ct-bg); border: 1px solid var(--ct-border); transform-origin: 0 0; z-index: 2; overflow: hidden; outline: none; container-type: size; }
+.ct-app[data-ct-panel] .ct-stage { right: var(--ct-notes-w); }
+.ct-app:not([data-ct-mode="stage"]) :is(.ct-stage, .ct-notes), .ct-app:not([data-ct-mode="overview"]) .ct-ov { visibility: hidden; }
+.ct-app[data-ct-busy] :is(.ct-stage, .ct-ov) { visibility: visible; }
+/* Three classes deep, so a host's document-view rules for the same elements lose here. */
+.ct-app .ct-stage :is([data-ct-deck], [data-ct-block], [data-ct-slide], [data-ct-page]) { max-width: none; margin: 0; border: 0; }
+.ct-app .ct-stage :is([data-ct-deck], [data-ct-block], [data-ct-slide]) { height: 100%; padding: 0; }
+.ct-stage [data-ct-block] { display: none; }
+.ct-stage [data-ct-block][data-ct-active] { display: flex; overflow: auto hidden; scroll-snap-type: x mandatory; overscroll-behavior: contain; scrollbar-width: none; }
+.ct-stage [data-ct-slide] { position: relative; flex: 0 0 100%; overflow-y: auto; scroll-snap-align: start; scroll-snap-stop: always; scroll-snap-type: y mandatory; overscroll-behavior-y: contain; scrollbar-width: none; }
+.ct-stage :is([data-ct-block], [data-ct-slide])::-webkit-scrollbar { display: none; }
+/* The side padding keeps the content in a centred column of --ct-measure, so the host's own margins and widths on the content stay as written. */
+.ct-app .ct-stage [data-ct-page] { min-height: 100%; scroll-snap-align: start; scroll-snap-stop: always; display: flex; flex-direction: column; justify-content: center; padding: clamp(1.4rem, 5cqh, 3.2rem) max(clamp(1.1rem, 6cqw, 5.5rem), (100cqw - var(--ct-measure)) / 2); font-size: clamp(1rem, min(2.05cqw, 3.7cqh), 3rem); }
+.ct-app[data-ct-paging="free"] [data-ct-slide] { scroll-snap-type: y proximity; }
+.ct-app[data-ct-paging="free"] [data-ct-page] { scroll-snap-stop: normal; }
+.ct-stage [data-ct-step] { transition: opacity .45s var(--ct-ease), transform .45s var(--ct-ease); }
+.ct-stage [data-ct-step]:not([data-ct-on]) { opacity: 0; transform: translateY(.45em); }
+.ct-stage tr[data-ct-step]:not([data-ct-on]) { visibility: collapse; }
+
+.ct-pager { display: flex; flex-direction: column; gap: 5px; position: absolute; right: .55rem; top: 50%; transform: translateY(-50%); z-index: 4; }
+.ct-pager i { display: block; width: 5px; height: 14px; background: var(--ct-border); }
+.ct-pager i[data-on] { background: linear-gradient(var(--ct-accent) calc(var(--f, 1) * 100%), color-mix(in srgb, var(--ct-accent) 30%, var(--ct-bg)) 0); }
+.ct-ctl { display: flex; gap: .35rem; position: absolute; right: 1.4rem; bottom: .6rem; z-index: 4; }
+.ct-ctl .ct-btn { min-width: 2.4rem; min-height: 2.4rem; font-size: .9rem; }
+
+/* ---- notes panel ---- */
+.ct-notes { position: absolute; top: 0; right: 0; bottom: 0; width: var(--ct-notes-w); background: var(--ct-bg); border: 1px solid var(--ct-border); padding: .9rem 1rem; overflow: auto; z-index: 6; }
+.ct-app:not([data-ct-panel]) .ct-notes { visibility: hidden; }
+.ct-notes h2 { font: 650 .66rem/1 var(--ct-mono); letter-spacing: .12em; margin: 0 0 .8rem; color: var(--ct-muted); }
+.ct-nb { font-size: 1rem; line-height: 1.75; }
+
+/* ---- notes view: the whole script, scrolled by hand ---- */
+.ct-script { display: none; position: absolute; inset: 0; overflow: auto; padding: 0 1rem 40vh; background: var(--ct-bg); z-index: 7; outline: none; }
+.ct-app[data-ct-mode="notes"] .ct-script { display: block; }
+.ct-sb { max-width: 40rem; margin: 0 auto; }
+.ct-sbh { position: sticky; top: 0; z-index: 1; display: flex; align-items: baseline; gap: .5rem; margin: 0; padding: .7rem 0 .5rem; font-size: .95rem; font-weight: 800; background: var(--ct-bg); }
+.ct-se { scroll-margin-top: 2.6rem; padding-bottom: 1rem; }
+.ct-app .ct-sh { display: flex; flex-direction: column; gap: .3rem; width: 100%; padding: .55rem .7rem; background: var(--ct-panel); font-size: 1rem; line-height: 1.3; }
+.ct-sn { padding: .5rem .7rem 0; font-size: 1.12rem; line-height: 1.8; }
+.ct-sn p, .ct-nb p { margin: 0 0 .8em; }
+
+@media (max-width: 760px) {
+  .ct-app { --ct-notes-w: 100%; }
+  .ct-rail { gap: .35rem; }
+  .ct-rg { gap: 2px; }
+  .ct-rl, .ct-title { display: none; }
+  .ct-rc i, .ct-rm { width: 6px; height: 4px; }
+  .ct-app[data-ct-panel] .ct-stage { right: 0; bottom: 42%; }
+  .ct-notes { top: 58%; }
+  /* room for the step buttons under the last line */
+  .ct-app .ct-stage [data-ct-page] { padding-bottom: 4.2rem; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ct-app :is(.ct-plane, .ct-layer, .ct-face, .ct-thumb, .ct-ring, .ct-rm, [data-ct-step]) { transition-duration: .01ms !important; }
+}

package/styles/index.css

@@ -0,0 +1,3 @@
+/* contour-deck styles: the entry that becomes contour-deck/style.css. */
+@import "./base.css";
+@import "./deck.css";