contour-deck 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,373 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

package/README.md

@@ -1,3 +1,262 @@
-# Temporary Holding Version
+# contour-deck
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://wayne930242.github.io/contour-deck/">
+    <picture>
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/tour-light.gif">
+      <img src="https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/tour.gif" alt="Open a slide from the outline, move left and right, scroll down its pages, and return to the outline" width="800">
+    </picture>
+  </a>
+</p>
+
+Outline-first slide decks on real DOM.
+A deck is blocks, slides, and pages: it opens on an outline of every block, a block opens into a left-right track of slides, and each slide scrolls down one page at a time.
+The core is plain TypeScript with no runtime dependency (7 KB of JavaScript and 3 KB of CSS, gzipped); the phone remote is a separate module that loads on first use.
+
+Status: 0.1.0 on npm (M1). The M2 client is on `main`, not yet released: phone remote, laser pointer, drawing, tilt pointing, and a presenter window ([Remote](#remote)); the relay it talks to is a separate small service ([docs/PROTOCOL.md](docs/PROTOCOL.md)). Live demo: https://wayne930242.github.io/contour-deck/
+The design is in [docs/DESIGN.md](docs/DESIGN.md) (Traditional Chinese); the HTML the core reads is in [docs/CONTRACT.md](docs/CONTRACT.md).
+
+## 看看它怎麼動
+
+[線上示範](https://wayne930242.github.io/contour-deck/)可以直接操作；[影片與截圖頁](https://wayne930242.github.io/contour-deck/media.html)有每一段的 mp4 與原尺寸截圖。
+下面的動畫是真實的鍵盤與滑鼠操作（圓圈是滑鼠，黑底小標是按下的鍵），用 `pnpm media` 重錄。
+
+| | |
+| --- | --- |
+| ![跨區塊移動：翻到區塊盡頭時拉遠再推進，位置列的圓點直接飛到另一個區塊](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/move.gif) | ![3D 結構：輪廓傾斜、頁疊成層，仍可點進投影片](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/structure.gif) |
+| 跨區塊移動：拉遠再推進，位置列的圓點直接飛到別的區塊 | 3D 結構：按 3，頁疊成層 |
+| ![步驟：表格一列一列出現，步驟用完才換頁](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/build.gif) | ![手機：講稿檢視、輪廓、舞台與往上滑的換頁](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/phone.gif) |
+| 步驟：空白鍵讓表格一列一列出現 | 手機：講稿檢視與往上滑換頁 |
+
+| | |
+| --- | --- |
+| ![輪廓：七個區塊的縮圖牆](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/overview.png) | ![3D 結構](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/overview-3d.png) |
+| 輪廓 | 3D 結構 |
+| ![舞台旁的講稿面板](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/notes.png) | ![淺色主題的舞台](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/light.png) |
+| 講稿面板（按 N） | 淺色主題 |
+
+## Use
+
+```ts
+import { createDeck } from "contour-deck";
+import "contour-deck/style.css";
+
+const root = document.querySelector<HTMLElement>("[data-ct-deck]")!;
+if (new URLSearchParams(location.search).has("view")) {
+  const deck = createDeck(root);
+  deck.on("exit", () => deck.destroy());
+}
+```
+
+Without the script the deck element is a plain document.
+`createDeck` moves that same element onto a stage inside a full-window shell (`.ct-app`), and `destroy()` puts it back.
+[demo/index.html](demo/index.html) is a complete host page.
+
+### Astro
+
+```ts
+// astro.config.ts: the Markdown side, see docs/PLUGINS.md
+import { remarkDeck } from "contour-deck/remark";
+import { rehypeDeck } from "contour-deck/rehype";
+
+const isDeck = file => file.data.astro?.frontmatter?.type === "slide";
+// remarkPlugins: [remarkDirective, [remarkDeck, { match: isDeck }], …]
+// rehypePlugins: […, [rehypeDeck, { match: isDeck }]]
+```
+
+```astro
+---
+import Deck from "contour-deck/astro";
+const { Content } = await render(post);
+---
+
+<button data-ct-start>START</button>
+<a href="?view=notes" data-ct-start="notes">Notes</a>
+
+<Deck docClass="prose" legacy>
+  <Content />
+</Deck>
+```
+
+`Deck` renders a wrapper around the slot, loads the stylesheet, and starts the core: on `?view=deck` or `?view=notes`, and on a click on any `[data-ct-start]` control (`data-ct-start="notes"` opens the notes view).
+It closes the deck on `exit`, gives the focus back to the control that opened it, and works under Astro's client router.
+
+| Prop | Meaning |
+| --- | --- |
+| `class` | Classes of the wrapper in both views. |
+| `docClass` | Classes the wrapper carries only while the deck is closed. Use it for a prose class: the open deck stays inside the wrapper, and such a class would restyle the stage and the shell. |
+| `paging`, `overview` | The options of the same name below. |
+| `legacy` | Accept old reveal.js links: `?view=slides&slide=h.v` opens the slide that carries that `data-legacy` index. |
+
+A page that is not Astro gets the same behaviour from `mountAll()` in `contour-deck/host`, with the wrapper written by hand (`<div data-ct-host data-ct-doc-class="prose" data-ct-legacy>`).
+
+### Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `paging` | `"snap"` | `"snap"`: one wheel or trackpad gesture moves one stop. `"free"`: native scrolling with proximity snap. |
+| `overview` | `"flat"` | `"3d"` opens the outline as the tilted 3D structure. |
+| `linear.skip` | `["appendix"]` | Block kinds the linear advance and the arrow keys never enter. |
+| `view` | from the URL | `"deck"` or `"notes"` (the speaker notes as a scrolling script, for a phone). |
+| `at` | from the URL | Entry position, such as `"4.4.2"` or a slide id. |
+| `url` | `true` | Read and write `?view=` and `?at=`. |
+| `labels` | Traditional Chinese | Interface text; pass the entries to replace. |
+| `remote` | none | A function the remote button and the `R` key call with the deck; it usually loads `contour-deck/remote`. Without it the deck has neither. See [Remote](#remote). |
+
+### API
+
+```ts
+deck.next();            // next step, down within the page, next page, next slide, next block
+deck.prev();
+deck.open("4.2");       // put a block on the stage
+deck.go("4.4.2");       // or deck.go("slide-id")
+deck.overview();        // back to the outline
+deck.slideBy(1);        // the next slide, as the right arrow key; -1 for the one before
+deck.pageBy(1);         // one stop down inside the slide, as the down arrow key
+deck.state;             // { mode, block, slide, page, step }; ordinals are 1-based
+deck.on("change", ({ mode, at, step }) => {});
+deck.on("exit", () => deck.destroy()); // Esc on the outline, or the ✕ button of the bar
+deck.on("destroy", () => {});          // once, at the start of destroy()
+deck.destroy();
+```
+
+On opening, the focus moves into the shell: to the stage, to the current thumbnail of the outline, or to the notes script.
+
+Each page receives `ct:enter` when it becomes the current page and `ct:leave` when it stops; both bubble.
+
+### Remote
+
+A phone controls the deck, points at it, and draws on it; a second window on the same computer shows the presenter's view.
+The code is `contour-deck/remote`, loaded on first use, so a reader who never presses `R` downloads none of it.
+
+```ts
+import { createDeck } from "contour-deck";
+
+const options = { relay: "wss://relay.example" }; // see "The relay" below
+const load = () => import("contour-deck/remote");
+const view = new URLSearchParams(location.search).get("view");
+
+if (view === "remote") load().then(remote => remote.remoteView(root, options)); // the phone
+else if (view === "presenter") load().then(remote => remote.presenterView(root, options)); // the presenter window
+else if (view) {
+  const deck = createDeck(root, { remote: deck => load().then(remote => remote.remoteHost(deck, root, options)).then(host => host.toggle()) });
+  deck.on("exit", () => deck.destroy());
+}
+```
+
+With Astro, `<Deck relay="wss://relay.example">` does all of this (`<Deck remote>` without a relay); so does `data-ct-relay` or `data-ct-remote` on a `[data-ct-host]` wrapper.
+
+How to connect:
+
+1. On the deck, press `R` (or the 遙控 button). The panel shows two QR codes.
+2. Scan 手機遙控 with the phone. It opens the same page as `?view=remote&room=…` and shows a 4-digit code.
+3. The deck shows the same code under 有手機要求控制. Compare the two screens and press 允許.
+4. The phone now has: position and clocks (whole talk and current block, from `data-minutes`), the notes, what the next step shows, 下一步 / 上一步 / 上一張 / 下一張 / 輪廓, and three pointing tools: 紅點 (drag on a small copy of the page), 畫筆 (draw on it; a page change clears the ink), and 傾斜 (hold a button and aim the phone like a laser pointer).
+5. 講稿, the other QR, is `?view=notes`: the script on the phone, turned by hand, with no connection at all.
+
+開啟講者視窗 in the panel opens `?view=presenter` in a second window of the same browser: the current page, the next step, the notes, and the clocks. It follows over `BroadcastChannel`, needs no relay, and takes the deck's keys; the mouse over its current page is the laser pointer.
+
+Tilt pointing reads the phone's orientation sensor (iOS asks for permission on the tap that enables it).
+校正 guides through five aims: the screen's centre, then its four corners, each marked by the dot on the deck. From these the phone knows where the screen is from where you stand, and keeps it for the session.
+Without calibration, the direction of the first press is the centre of a screen ±20° wide and ±12° high.
+When the pointer drifts, aim at the centre and press 重新置中; aiming past an edge also drags the calibration along, as a mouse at the edge of a screen.
+
+Security, in three lines: the relay only forwards small messages (position, commands, pointer coordinates) between the deck and at most four phones; notes, block titles, and slide content never pass through it, because the phone loads the page itself.
+The room in the QR lets a phone ask; only the deck's tab holds the key the room is hashed from, so nobody else can take the deck's seat at the relay and hear what the phones send.
+Control belongs to the one phone the presenter allowed on the deck after comparing the code; everything any other guest sends is ignored, and the relay removes a denied guest, so a QR photographed from the projector yields only a request to deny.
+
+| Option of `remoteHost`, `remoteView`, `presenterView` | Default | Meaning |
+| --- | --- | --- |
+| `relay` | none | Base URL of the relay, `wss://…` or `https://…`. Without it the remote stays on this computer: presenter window and notes link only. |
+| `qr` | built-in | `(text) => svgString`, for a site that already ships a QR library: `text => QRCode.toString(text, { type: "svg" })`. The built-in encoder takes links up to 287 bytes; a longer link shows as text. |
+| `skip` | `["appendix"]` | Block kinds whose minutes are not planned time; keep it equal to `linear.skip`. |
+| `labels` | Traditional Chinese | Interface text of the panel, the phone, and the presenter window. |
+| `nonce` | none | Nonce for the `<style>` the module injects, for a page with a `style-src` policy. |
+| `room` (views only) | `?room=` | The room to join. |
+
+`remoteHost(deck, root, options)` resolves to the session of that deck, creating it once: `toggle()` shows or hides the panel, `end()` takes control back and closes the room, `room` is its name.
+It is a promise because the room is the SHA-256 of the session's key (`crypto.subtle`, so with a relay the page needs https or localhost).
+The key, the paired phone's token, and the clock live in `sessionStorage`, so a reload of the deck or of the phone continues the same session; the Astro host and the demo restart it by themselves after a reload.
+With the Astro component, pass a QR encoder or labels through `configureRemote({ qr })` from `contour-deck/host`.
+The remote follows the first deck of a page.
+
+The clock starts with the first move on the stage (not when a slide is opened from the outline) and is reset from the panel.
+The laser dot eases towards its target and fades when released; with `prefers-reduced-motion` it jumps and does not fade.
+
+#### The relay
+
+The relay is a WebSocket forwarder, one room per talk, specified in [docs/PROTOCOL.md](docs/PROTOCOL.md): rooms, the pairing messages, close codes, and limits (2 KB frames, 60 messages a second, 4 guests).
+`relay(url, { room, role, key })` and `broadcast(room)` are the two `Transport`s (`send`, `subscribe`, `watch`, `reconnect`, `close`, `status`); the relay one reconnects with backoff, except after `4003` (removed by the host) and `4009` (another tab of the session took the host seat).
+The demo takes a relay from the query string, the deployed one or one on this machine: `https://wayne930242.github.io/contour-deck/?relay=wss://contour-relay.wayne930242.workers.dev&view=deck`, or `?relay=ws://localhost:8787`; it ignores any other.
+The phone must be able to open the page's URL, so a deck on `localhost` needs a tunnel or the LAN address for the phone part.
+
+### Keys
+
+| Key | On the stage | On the outline |
+| --- | --- | --- |
+| `Space`, `Enter`, `PageDown` | advance one step | open the current slide |
+| `Shift+Space`, `PageUp`, `Backspace` | back one step | |
+| `←` `→` | previous, next slide | move between thumbnails |
+| `↑` `↓` | previous, next stop | move between thumbnails |
+| `Home`, `End` | first, last slide of the block | |
+| `N` | notes panel | |
+| `R` | remote panel (with the `remote` option) | remote panel |
+| `Esc`, `O` | outline | `Esc` leaves the deck (`exit`) |
+| `3` | | 3D structure |
+
+### URL
+
+`?view=deck&at=4.4.2` is the second page of the fourth slide of the fourth block, counted from 1.
+`at` also takes the id of a slide, a page, or an element inside one.
+`?view=notes` opens the notes view.
+The core removes both parameters in `destroy()` and leaves the others alone.
+
+### Theme and host styles
+
+- Set `--ct-bg`, `--ct-fg`, `--ct-accent`, `--ct-accent-fg`, `--ct-border`, `--ct-muted`, `--ct-mono`, and `--ct-measure` on `.ct-app`.
+  By default the colours follow the site's `--background`, `--foreground`, `--accent`, `--accent-foreground`, `--border`, and `--muted-foreground`.
+- A page keeps its content in a centred column of `--ct-measure` through its own side padding, so margins and widths the host sets on the content stay as written.
+  The type of a page follows the size of the stage and never goes below `1rem`; sizes the host writes in `em` follow it, sizes in `rem` do not.
+- The open deck keeps its ancestors, so content styles that depend on them still apply.
+  Document-view styles for the deck's own elements (slide cards, block headings) must stop applying when it opens: scope them to the deck's original parent with a child combinator, as `demo/demo.css` does with `.doc > [data-ct-deck] …`.
+  A class that styles every descendant (a prose class) cannot be scoped that way: take it off the ancestor while the deck is open, as `Deck`'s `docClass` does.
+- The shell is `position: fixed`, so no ancestor of the deck element may have a `transform`, `filter`, or `contain` that captures fixed descendants.
+
+## Layout
+
+```text
+src/core/      the core: model, stops, gestures, navigator, outline, rail, notes, transitions, deck
+src/remote/    contour-deck/remote: protocol, transports, pairing, clock, tilt math, QR, and the three views
+src/remark/    Markdown directives (block, vertical, summary, build)
+src/rehype/    builds the deck > block > slide > page HTML
+src/astro/     Deck.astro and the host script it runs (also contour-deck/host)
+styles/        index.css is the entry of contour-deck/style.css
+demo/          a plain-HTML deck that follows the contract, and media.html (clips and stills)
+docs/media/    GIF, mp4, and PNG made by scripts/media.mjs (not in the npm package)
+tests/unit/    Vitest, tests/unit/**/*.test.ts
+tests/browser/ Playwright, tests/browser/**/*.spec.ts, run against demo/; relay-stub.ts is the relay of docs/PROTOCOL.md in the test process
+```
+
+Every module under `src/` is compiled to the same path under `dist/`, so a new subpath export only needs an entry in `package.json`.
+`.astro` files are copied there as they are.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `pnpm install` | Install dependencies. |
+| `pnpm exec playwright install chromium` | Once, for the browser tests. |
+| `pnpm typecheck` | Type-check `src/`, `tests/`, and `scripts/`. |
+| `pnpm build` | Compile to `dist/` and build the demo assets in `demo/assets/`. |
+| `pnpm test` | Unit tests. |
+| `pnpm test:browser` | Build, then run the browser tests against the demo in Chromium. |
+| `CT_BROWSERS=all pnpm test:browser` | The same in Chromium, Firefox, and WebKit (`pnpm exec playwright install firefox webkit` once). |
+| `pnpm size` | Minified gzip size of the core and the CSS against the budgets (12 KB, 6 KB), and of the parts of the remote. |
+| `pnpm demo` | Build and serve the demo on `http://127.0.0.1:41731/demo/`. |
+| `pnpm media` | Record the clips and stills in `docs/media/` (needs `ffmpeg` and Chromium); the Pages workflow publishes the mp4 and png files next to the demo. |
+
+The demo also opens straight from the file system: `demo/index.html` after `pnpm build`.
+
+## License
+
+[MPL-2.0](LICENSE)