@steamfield/decks 1.0.0-rc.1 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/dist/cli.js +1 -1
  2. package/dist/control-tray.css +84 -0
  3. package/dist/go-to-dialog.css +57 -0
  4. package/dist/{index-BURtH7IB.d.ts → index-D3Yj4yT6.d.ts} +11 -2
  5. package/dist/{index-BV_-6L5L.d.ts → index-DG8UcGQd.d.ts} +77 -1
  6. package/dist/{index-B2n69xrC.d.ts → index-zg-z6HTy.d.ts} +18 -2
  7. package/dist/index.d.ts +3 -3
  8. package/dist/index.js +2 -2
  9. package/dist/kit/term/live-term.module.css +36 -0
  10. package/dist/kit.d.ts +21 -6
  11. package/dist/kit.js +252 -8
  12. package/dist/live-term.module.css +36 -0
  13. package/dist/magic-move.css +30 -0
  14. package/dist/mark.css +34 -0
  15. package/dist/motion.d.ts +2 -2
  16. package/dist/motion.js +1 -1
  17. package/dist/node.d.ts +5 -1
  18. package/dist/node.js +1 -1
  19. package/dist/plugin/skills/building-a-deck/references/workflow.md +10 -0
  20. package/dist/plugin/skills/deck-design/references/layout.md +2 -0
  21. package/dist/plugin/skills/deck-motion/references/motion.md +38 -1
  22. package/dist/plugin/skills/working-with-decks/references/project.md +4 -0
  23. package/dist/presenter-view.css +14 -0
  24. package/dist/{prose-patterns-DPqjGBFu.js → prose-patterns-D-tdt0Ab.js} +3 -1
  25. package/dist/{prose-scan-BrWZ7gxZ.js → prose-scan-ni8g6pc-.js} +2 -2
  26. package/dist/{src-DizFoqYt.js → src--lhAQ29p.js} +348 -43
  27. package/dist/{src-C-OfT72W.js → src-BNyL3q7j.js} +212 -3
  28. package/dist/{src-CmQgaG1b.js → src-Cxck-eLP.js} +588 -68
  29. package/dist/term/shell_pty.py +38 -0
  30. package/dist/term/zsh/.zshrc +4 -0
  31. package/dist/term-protocol-B_qHRDEp.js +11 -0
  32. package/dist/xterm-host-C6OjffSm.js +282 -0
  33. package/docs/README.md +1 -0
  34. package/docs/cli.md +2 -1
  35. package/docs/code-blocks.md +31 -0
  36. package/docs/config.md +1 -0
  37. package/docs/getting-started.md +2 -1
  38. package/docs/kit.md +7 -6
  39. package/docs/migrating-from-slidev.md +4 -0
  40. package/docs/motion.md +25 -1
  41. package/docs/presenting.md +16 -1
  42. package/docs/slides.md +20 -1
  43. package/docs/terminal.md +97 -0
  44. package/package.json +4 -1
@@ -0,0 +1,38 @@
1
+ """Run a command on a pseudo-terminal of a set size, relaying stdin and stdout over pipes.
2
+
3
+ usage: shell_pty.py ROWS COLS COMMAND [ARG...]
4
+ The dev-server terminal plugin spawns this, because Node has no pty of its own and macOS
5
+ script(1) refuses a piped stdin. When stdin closes, the terminal is hung up, so the command
6
+ does not outlive the dev server. Exits with the command's exit status.
7
+ """
8
+ import fcntl
9
+ import os
10
+ import pty
11
+ import select
12
+ import struct
13
+ import sys
14
+ import termios
15
+
16
+ rows, cols = int(sys.argv[1]), int(sys.argv[2])
17
+ pid, fd = pty.fork()
18
+ if pid == 0:
19
+ os.execvp(sys.argv[3], sys.argv[3:])
20
+ fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
21
+ while True:
22
+ readable, _, _ = select.select([fd, 0], [], [])
23
+ try:
24
+ if fd in readable:
25
+ data = os.read(fd, 65536)
26
+ if not data:
27
+ break
28
+ os.write(1, data)
29
+ if 0 in readable:
30
+ data = os.read(0, 65536)
31
+ if not data:
32
+ break
33
+ os.write(fd, data)
34
+ except OSError:
35
+ break
36
+ os.close(fd)
37
+ _, status = os.waitpid(pid, 0)
38
+ sys.exit(os.waitstatus_to_exitcode(status) if os.WIFEXITED(status) else 1)
@@ -0,0 +1,4 @@
1
+ # A private ZDOTDIR and zsh -d keep personal and global rc files off the projector.
2
+ PROMPT_EOL_MARK=''
3
+ PROMPT=$'\n%{\e]133;A\a%}%B%F{green}\$ %f%b'
4
+ zle_highlight=(default:fg=green,bold)
@@ -0,0 +1,11 @@
1
+ // ../core/src/term-protocol.ts
2
+ /** Browser to server. */
3
+ const TERM_ATTACH = "deck-term:attach";
4
+ const TERM_POSITION = "deck-term:position";
5
+ const TERM_INPUT = "deck-term:input";
6
+ /** Server to browser. */
7
+ const TERM_READY = "deck-term:ready";
8
+ const TERM_DATA = "deck-term:data";
9
+ const TERM_STATE = "deck-term:state";
10
+ const TERM_GONE = "deck-term:gone";
11
+ export { TERM_POSITION as a, TERM_INPUT as i, TERM_DATA as n, TERM_READY as o, TERM_GONE as r, TERM_STATE as s, TERM_ATTACH as t };
@@ -0,0 +1,282 @@
1
+ import { useLayoutEffect, useRef } from "react";
2
+ import { jsx } from "react/jsx-runtime";
3
+ import styles from "./live-term.module.css";
4
+ import { Terminal } from "@xterm/xterm";
5
+ import "@xterm/xterm/css/xterm.css";
6
+ // ../kit/src/term/output-pacer.ts
7
+ /** Pace bursts without delaying keystrokes, short replies or session replays. */
8
+ function createOutputPacer(write) {
9
+ let pending = "";
10
+ let deadline = 0;
11
+ let recentLines = 0;
12
+ let windowStarted = 0;
13
+ let timer;
14
+ const interval = 1e3 / 30;
15
+ const clear = () => {
16
+ clearTimeout(timer);
17
+ timer = void 0;
18
+ pending = "";
19
+ recentLines = 0;
20
+ windowStarted = Date.now();
21
+ };
22
+ const flush = () => {
23
+ const chunk = pending;
24
+ clear();
25
+ if (chunk) write(chunk, false);
26
+ };
27
+ const drain = () => {
28
+ timer = void 0;
29
+ const lines = pending.split("\n");
30
+ const ticks = Math.max(1, Math.floor((deadline - Date.now()) / interval));
31
+ const count = Math.max(1, Math.ceil(lines.length / ticks));
32
+ write(lines.splice(0, count).join("\n") + (lines.length ? "\n" : ""), false);
33
+ pending = lines.join("\n");
34
+ if (pending) timer = setTimeout(drain, interval);
35
+ };
36
+ return {
37
+ push(chunk, replay = false, immediate = false) {
38
+ if (replay) {
39
+ clear();
40
+ write(chunk, true);
41
+ return;
42
+ }
43
+ if (immediate) {
44
+ flush();
45
+ write(chunk, false);
46
+ return;
47
+ }
48
+ if (Date.now() - windowStarted >= interval) {
49
+ windowStarted = Date.now();
50
+ recentLines = 0;
51
+ }
52
+ const lines = chunk.split("\n").length - 1;
53
+ if (timer === void 0 && recentLines + lines <= 3) {
54
+ recentLines += lines;
55
+ write(chunk, false);
56
+ return;
57
+ }
58
+ pending += chunk;
59
+ if (timer === void 0) {
60
+ deadline = Date.now() + 1500;
61
+ timer = setTimeout(drain, interval);
62
+ }
63
+ },
64
+ flush,
65
+ dispose: clear
66
+ };
67
+ }
68
+ // ../kit/src/term/terminal-face.ts
69
+ /** Fit xterm's measured grid at a whole device-pixel advance, without scaling it. */
70
+ function terminalFace(terminal, fontFamily, width, height, devicePixelRatio) {
71
+ const ruler = document.createElement("canvas").getContext("2d");
72
+ if (!ruler) throw new Error("no 2d canvas to measure the terminal font");
73
+ ruler.font = `1000px ${fontFamily}`;
74
+ const advance = ruler.measureText("W").width / 1e3;
75
+ const screen = terminal.element?.querySelector(".xterm-screen");
76
+ if (!screen) throw new Error("no xterm screen to measure");
77
+ const scrollbar = 6;
78
+ let cell = Math.floor((width - scrollbar) * devicePixelRatio / terminal.cols);
79
+ for (; cell >= 1; cell--) {
80
+ terminal.options.fontSize = cell / (advance * devicePixelRatio);
81
+ const gridWidth = screen.offsetWidth;
82
+ const gridHeight = screen.offsetHeight;
83
+ if (Number.isInteger(gridWidth * devicePixelRatio / terminal.cols) && gridWidth + scrollbar <= width && gridHeight <= height) return {
84
+ gridWidth,
85
+ gridHeight,
86
+ rowHeight: gridHeight / terminal.rows,
87
+ scrollbar,
88
+ left: (width - gridWidth - scrollbar) / 2,
89
+ top: (height - gridHeight) / 2
90
+ };
91
+ }
92
+ throw new Error(`terminal grid ${terminal.cols} by ${terminal.rows} cannot fit ${width} by ${height}`);
93
+ }
94
+ // ../kit/src/term/xterm-host.tsx
95
+ function XtermHost({ connection, rows, cols, scale, onReady }) {
96
+ const host = useRef(null);
97
+ useLayoutEffect(() => {
98
+ const target = host.current;
99
+ if (!target || scale <= 0) return;
100
+ let term;
101
+ let unsubscribe;
102
+ let cleanupOutput;
103
+ let cleanupWheel;
104
+ let cleanupFit;
105
+ let disposed = false;
106
+ const css = getComputedStyle(target.parentElement ?? target);
107
+ const fontFamily = css.fontFamily;
108
+ const fontSize = Number.parseFloat(css.fontSize);
109
+ const foreground = css.color;
110
+ const color = (name) => css.getPropertyValue(`--deck-term-${name}`).trim() || foreground;
111
+ const colors = {
112
+ foreground,
113
+ background: css.backgroundColor,
114
+ cursor: color("cursor"),
115
+ selectionBackground: color("selection"),
116
+ black: color("black"),
117
+ red: color("red"),
118
+ green: color("green"),
119
+ yellow: color("yellow"),
120
+ blue: color("blue"),
121
+ magenta: color("magenta"),
122
+ cyan: color("cyan"),
123
+ white: color("white"),
124
+ brightBlack: color("bright-black"),
125
+ brightRed: color("bright-red"),
126
+ brightGreen: color("bright-green"),
127
+ brightYellow: color("bright-yellow"),
128
+ brightBlue: color("bright-blue"),
129
+ brightMagenta: color("bright-magenta"),
130
+ brightCyan: color("bright-cyan"),
131
+ brightWhite: color("bright-white")
132
+ };
133
+ Promise.all([document.fonts.load(`${fontSize}px ${fontFamily}`), document.fonts.ready]).then(() => {
134
+ if (disposed) return;
135
+ try {
136
+ const frame = target.parentElement;
137
+ if (!frame) throw new Error("no terminal frame to measure");
138
+ term = new Terminal({
139
+ rows,
140
+ cols,
141
+ fontFamily,
142
+ fontSize: fontSize * scale,
143
+ letterSpacing: 0,
144
+ lineHeight: 1.12,
145
+ theme: colors,
146
+ allowTransparency: true,
147
+ drawBoldTextInBrightColors: false,
148
+ cursorBlink: false,
149
+ scrollback: 2e3,
150
+ overviewRuler: {
151
+ width: 6,
152
+ showTopBorder: false,
153
+ showBottomBorder: false
154
+ },
155
+ logLevel: "off"
156
+ });
157
+ term.attachCustomKeyEventHandler((event) => {
158
+ if (event.key !== "Escape") return true;
159
+ event.preventDefault();
160
+ event.stopPropagation();
161
+ term?.blur();
162
+ return false;
163
+ });
164
+ term.open(target);
165
+ const terminal = term;
166
+ const fit = () => {
167
+ const bounds = frame.getBoundingClientRect();
168
+ const face = terminalFace(terminal, fontFamily, bounds.width, bounds.height, window.devicePixelRatio);
169
+ target.style.width = `${face.gridWidth + face.scrollbar}px`;
170
+ target.style.height = `${face.gridHeight}px`;
171
+ target.style.marginLeft = `${face.left / scale}px`;
172
+ target.style.marginTop = `${face.top / scale}px`;
173
+ target.style.transform = `scale(${1 / scale})`;
174
+ return face;
175
+ };
176
+ let face = fit();
177
+ const refit = () => {
178
+ if (disposed) return;
179
+ try {
180
+ face = fit();
181
+ } catch (error) {
182
+ connection.unavailable(`terminal could not fit: ${error instanceof Error ? error.message : String(error)}`);
183
+ }
184
+ };
185
+ const observer = new ResizeObserver(refit);
186
+ observer.observe(frame);
187
+ let resolution = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
188
+ const changedDpr = () => {
189
+ if (disposed) return;
190
+ resolution.removeEventListener("change", changedDpr);
191
+ refit();
192
+ resolution = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
193
+ resolution.addEventListener("change", changedDpr);
194
+ };
195
+ resolution.addEventListener("change", changedDpr);
196
+ cleanupFit = () => {
197
+ observer.disconnect();
198
+ resolution.removeEventListener("change", changedDpr);
199
+ };
200
+ const rendered = terminal.onRender(() => {
201
+ if (disposed || !target.querySelector(".xterm-rows")?.textContent?.trim()) return;
202
+ onReady(true);
203
+ rendered.dispose();
204
+ });
205
+ let replays = 0;
206
+ const paced = createOutputPacer((chunk, replay) => {
207
+ if (replay) {
208
+ replays++;
209
+ terminal.options.disableStdin = true;
210
+ }
211
+ terminal.write(chunk, () => {
212
+ if (disposed) return;
213
+ if (replay) {
214
+ replays--;
215
+ terminal.options.disableStdin = replays > 0;
216
+ }
217
+ terminal.scrollToBottom();
218
+ });
219
+ });
220
+ term.onData((data) => {
221
+ paced.flush();
222
+ connection.input(data);
223
+ });
224
+ cleanupOutput = paced.dispose;
225
+ unsubscribe = connection.subscribeOutput(paced.push);
226
+ let remainder = 0;
227
+ const wheel = (event) => {
228
+ event.preventDefault();
229
+ event.stopPropagation();
230
+ const lineHeight = face.rowHeight;
231
+ const pixels = event.deltaY * (event.deltaMode === 1 ? lineHeight : event.deltaMode === 2 ? rows * lineHeight : 1);
232
+ remainder += pixels / lineHeight;
233
+ const lines = Math.trunc(remainder);
234
+ remainder -= lines;
235
+ if (lines) terminal.scrollLines(lines);
236
+ };
237
+ frame.addEventListener("wheel", wheel, {
238
+ passive: false,
239
+ capture: true
240
+ });
241
+ cleanupWheel = () => frame.removeEventListener("wheel", wheel, true);
242
+ } catch (error) {
243
+ connection.unavailable(`terminal could not open: ${error instanceof Error ? error.message : String(error)}`);
244
+ }
245
+ }).catch((error) => {
246
+ if (!disposed) connection.unavailable(`terminal font could not load: ${error instanceof Error ? error.message : String(error)}`);
247
+ });
248
+ return () => {
249
+ disposed = true;
250
+ onReady(false);
251
+ unsubscribe?.();
252
+ cleanupOutput?.();
253
+ cleanupWheel?.();
254
+ cleanupFit?.();
255
+ term?.dispose();
256
+ };
257
+ }, [
258
+ connection,
259
+ rows,
260
+ cols,
261
+ scale,
262
+ onReady
263
+ ]);
264
+ return /* @__PURE__ */ jsx("div", {
265
+ className: styles.viewport,
266
+ children: /* @__PURE__ */ jsx("div", {
267
+ ref: host,
268
+ className: styles.host,
269
+ role: "application",
270
+ "aria-label": "Live terminal",
271
+ onKeyDown: (event) => event.stopPropagation(),
272
+ onKeyUp: (event) => event.stopPropagation(),
273
+ style: {
274
+ fontVariantLigatures: "none",
275
+ width: `${scale * 100}%`,
276
+ height: `${scale * 100}%`,
277
+ transform: `scale(${1 / scale})`
278
+ }
279
+ })
280
+ });
281
+ }
282
+ export { XtermHost };
package/docs/README.md CHANGED
@@ -15,6 +15,7 @@ Each page stands alone. Read the one that answers your question.
15
15
  | [cli.md](cli.md) | What do `decks new`, `check`, `lint`, `hook`, `export`, `shot` and `init` do? |
16
16
  | [migrating-from-slidev.md](migrating-from-slidev.md) | How do I move a deck from `slidev-addon-decks`? |
17
17
  | [presenting.md](presenting.md) | Which keys do what, and how do the presenter window, overview, sync and text sizing behave? |
18
+ | [terminal.md](terminal.md) | How do I run real commands in a terminal pane on a slide, and what does the deck show when it can't? |
18
19
  | [kit.md](kit.md) | What does `@steamfield/decks/kit` provide: theme, story stages, `OpenChart`, the `story` transition? |
19
20
 
20
21
  ## Not built yet
package/docs/cli.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # The decks command
2
2
 
3
- `decks dev` and `decks build` are in [getting-started.md](getting-started.md). This page covers the rest. Every command that takes a deck accepts an alias from `decks.json` or a directory, and a bare name that is neither resolves under `_config.decksDir` (default `decks/`).
3
+ `decks dev` and `decks build` are in [getting-started.md](getting-started.md); `decks dev --live-term` is in [terminal.md](terminal.md). This page covers the rest. Every command that takes a deck accepts an alias from `decks.json` or a directory, and a bare name that is neither resolves under `_config.decksDir` (default `decks/`).
4
4
 
5
5
  ## `decks new <alias> [dir] [--story] [--author "Name"] [--url example.com]`
6
6
 
@@ -18,6 +18,7 @@ Checks the whole project and exits 1 if anything is wrong, one problem per line:
18
18
  | `<alias>: <message>` | The deck's config failed to load. |
19
19
  | `no slides: <alias>` | The deck has no visible slides (`dev` and `build` would refuse it). |
20
20
  | `<alias>: slide name: <file>` | A slide file is not `NN-slug.mdx`, or two share a number. |
21
+ | `<alias>: notes: <file> has [click] cues for N click(s), but the slide has M` | A visible slide's notes use `[click]` markers, and they cover a different number of clicks than the slide has, so cues would highlight on the wrong step. Notes with no markers are not checked. |
21
22
  | `N error-level prose hit(s)` | `decks lint` finds error-level patterns. |
22
23
 
23
24
  ## `decks lint [alias...] [--stdin]`
@@ -71,6 +71,37 @@ At click 0 line 2 is emphasized, at click 1 lines 4 and 5, at click 2 every line
71
71
 
72
72
  A block with `k` steps adds `at + k - 1` to the slide's click total, so the slide above has two clicks with no `clicks:` in its frontmatter. A block without braces uses no clicks. See [motion.md](motion.md) for how the total is counted.
73
73
 
74
+ ## Magic move
75
+
76
+ A magic-move fence morphs one code block into the next on a click: tokens that stay move to their new place, removed ones fade out and new ones fade in. The syntax is Slidev's, so a Slidev fence pastes in unchanged. Open with four backticks, the language `md` (or `markdown`) and `magic-move`, then put ordinary code fences inside, one per version.
77
+
78
+ `examples/motion/slides/32-magic-move.mdx`:
79
+
80
+ `````mdx
81
+ ````md magic-move "greet.ts" {lines: true}
82
+ ```ts {1}
83
+ const greeting = "Hello";
84
+ ```
85
+
86
+ ```ts {1|2}
87
+ const greet = (name: string) => `Hello, ${name}`;
88
+ greet("Ada");
89
+ ```
90
+
91
+ ```ts {all}
92
+ export function greet(name: string) {
93
+ return `Hello, ${name}!`;
94
+ }
95
+ ```
96
+ ````
97
+ `````
98
+
99
+ After `magic-move` come an optional title, either quoted (`"greet.ts"`) or in brackets (`[greet.ts]`), and an optional options object: `at` (the click of the first version, default 0) and `lines` (line numbers, default off). Each inner fence can have its own `{...}` line emphasis, as in a plain block, and its own `lines`.
100
+
101
+ Each version holds for as many clicks as it has emphasis steps, at least one, and the next click morphs to the next version. The slide above shows version 1 at click 0, version 2 with line 1 then line 2 emphasized at clicks 1 and 2, and version 3 at click 3: `at` plus every version's step count, minus 1, so 3 clicks with no `clicks:` in the frontmatter.
102
+
103
+ The morph plays only on a forward step in the play view with live motion. Going back, jumping, reloading, the presenter window, the overview and print show the version for the click at once, and each printed click page shows its own version. Slidev's `{*}` emphasis is not supported; use `{all}`. A fence that does not parse is a compile error naming the slide and the line.
104
+
74
105
  ## Languages
75
106
 
76
107
  The language is the first word on the fence. Any language Shiki bundles works. A block with no language is plain text. An unknown language is rendered as plain text and logs a warning naming the file.
package/docs/config.md CHANGED
@@ -28,6 +28,7 @@ Only `title` is required. An unknown key is an error that lists the known ones.
28
28
  | `credit` | `boolean` | `true` | The "Created with Decks" credit on every slide. `false` removes it. |
29
29
  | `vite` | Vite `UserConfig` | none | Merged into the framework's Vite config. `vite.plugins` are added after the framework's. |
30
30
  | `mdx` | `{ remarkPlugins?: PluggableList; rehypePlugins?: PluggableList }` | none | Plugins added to the slide compiler. Each key, when present, must be an array. |
31
+ | `term` | `{ dirs?: Record<string, string> }` | none | Working directories a `LiveTerm` pane can start in, by key, relative to the deck. Each must exist when `decks dev --live-term` starts. See [terminal.md](terminal.md). |
31
32
 
32
33
  Examples of each:
33
34
 
@@ -58,7 +58,7 @@ npx -p @steamfield/decks decks build hello
58
58
 
59
59
  Or add scripts to `package.json` (`"dev": "decks dev hello"`, `"build": "decks build hello"`), which run the installed bin, and use `bun run dev` or `npm run dev`. The rest of the guide writes the command as `decks` for short.
60
60
 
61
- ### `decks dev <deck> [--port <n>] [--open]`
61
+ ### `decks dev <deck> [--port <n>] [--open] [--live-term]`
62
62
 
63
63
  Serves the deck with live updates and prints its URL.
64
64
 
@@ -66,6 +66,7 @@ Serves the deck with live updates and prints its URL.
66
66
  | --- | --- | --- |
67
67
  | `--port <n>` | first free port from 3030 up | A whole number from 0 to 65535. An explicit port is strict: if it is taken the command fails instead of moving to another. `0` lets the OS pick. |
68
68
  | `--open` | off | Open the deck in a browser. |
69
+ | `--live-term` | off | Run real shells in the deck's `LiveTerm` panes, on macOS and Linux. See [terminal.md](terminal.md). `decks build` and the other commands reject it. |
69
70
 
70
71
  What an edit does while `dev` runs:
71
72
 
package/docs/kit.md CHANGED
@@ -48,6 +48,7 @@ export { StoryCover } from "@steamfield/decks/kit";
48
48
  | `DUR`, `SETTLE`, `DRAW`, `TRACE`, `SETTLE_CSS`, `DRAW_CSS`, `TRACE_CSS`, `easedStagger` | The story duration table (seconds), three gsap ease names, the same curves as CSS strings, and an eased stagger offset. |
49
49
  | `xScale`, `yScale`, `clamp01`, `stagger` | Linear scales (d3-scale) for stage coordinates, a 0 to 1 clamp, and per-item progress within one staggered beat. |
50
50
  | `FILTER_IDS`, `filterUrl` | SVG filters every `StoryStage` defines (marker textures and a glow), referenced as `filter={filterUrl(FILTER_IDS.glow)}`. |
51
+ | `LiveTerm`; type `LiveTermStatus` | A real shell on a slide, one command per click, with a fallback wherever a shell can't run. See [terminal.md](terminal.md). |
51
52
  | `gsap` | The motion package's gsap instance, re-exported. |
52
53
 
53
54
  The package also exports `@steamfield/decks/kit/styles.css`. Nothing else is public.
@@ -72,11 +73,11 @@ installTheme(resolveTheme(deckTheme));
72
73
  | `theme()` | Returns the active theme. Throws if none is installed. |
73
74
  | `ink(hue, step)` | One color of a ramp. `hue` is `"cyan"`, `"amber"`, `"rose"`, `"emerald"`, `"violet"` or `"slate"`; `step` is 1 to 4, darkest to lightest. |
74
75
 
75
- `setup.ts` runs before any component module, so a component may call `ink()` at module level, as `examples/building-for-agents/components/OpenChartStage.tsx` does:
76
+ `setup.ts` runs before any component module, so a component may call `ink()` at module level, as `examples/opendata-pitch/components/BootstrapStage.tsx` does:
76
77
 
77
78
  ```tsx
78
- const DATA = ink("cyan", 2);
79
- const NEUTRAL = ink("slate", 1);
79
+ const RULE_INK = ink("slate", 1);
80
+ const DISK_WALL = ink("amber", 3);
80
81
  ```
81
82
 
82
83
  ### A deck's `theme.json`
@@ -330,15 +331,15 @@ The chart animates in when its slide is arrived at on click 0 in the play view,
330
331
 
331
332
  The chart draws at screen size, not canvas size, so font sizes in a spec are screen pixels. Multiply them by the frame scale: `useFrameScale()` returns it, and `scaleChartTheme(theme, scale)` applies it to a chart theme's font sizes and axis spacing. `slideChartTheme` is a chart theme that reads its colors and fonts from the installed kit theme, and `slideChartAnimation` is the entrance timing for slides.
332
333
 
333
- Condensed from `examples/building-for-agents/components/OpenChartStage.tsx`:
334
+ A stage that draws one chart from a module-level `SPEC`, colored with a module-level `DATA = ink("cyan", 2)`:
334
335
 
335
336
  ```tsx
336
337
  const scale = useFrameScale();
337
338
  const chartSpec = useMemo<ComponentProps<typeof OpenChart>["spec"]>(() => {
338
339
  const base = scaleChartTheme(slideChartTheme, scale);
339
340
  return {
340
- ...README_SPEC,
341
- data: [...README_SPEC.data],
341
+ ...SPEC,
342
+ data: [...SPEC.data],
342
343
  theme: { ...base, colors: { ...base.colors, categorical: [DATA] } },
343
344
  animation: slideChartAnimation,
344
345
  };
@@ -35,6 +35,10 @@ Decks used to be a Slidev addon, `slidev-addon-decks`. It is now its own React f
35
35
  | `<!-- notes -->` at the end of a page | `<Notes>...</Notes>`, `[click]` markers included |
36
36
  | `<!-- lint-allow: id -->` on a line | `{/* lint-allow: id */}` on the same line |
37
37
  | `routeEmbedNavigation` from `slidev-addon-decks/composables/embed-navigation` | `routeEmbedNavigation` from `@steamfield/decks` |
38
+ | `v-mark` (`v-mark.circle`, `v-mark.box`, ...) | `<Mark kind="circle" at={n}>` around the text; see [motion.md](motion.md) |
39
+ | a four-backtick `md magic-move` fence | the same fence; `{*}` emphasis becomes `{all}`. See [code-blocks.md](code-blocks.md) |
40
+ | `<Toc />`, `<Link to="5">` | `<Toc />`, `<Link to={5}>` (a number); see [slides.md](slides.md) |
41
+ | the bottom-left navigation controls and `g` | the control tray and `g`; see [presenting.md](presenting.md) |
38
42
 
39
43
  ## Commands
40
44
 
package/docs/motion.md CHANGED
@@ -14,10 +14,11 @@ When a slide's frontmatter has no `clicks`, the total is read from the MDX sourc
14
14
 
15
15
  | Written in the slide | Contributes |
16
16
  | --- | --- |
17
- | `Step`, `Stagger`, `Highlight`, `Draw` with `at` and optional `until` | `until` if present, else `at` |
17
+ | `Step`, `Stagger`, `Highlight`, `Draw`, `Mark` with `at` and optional `until` | `until` if present, else `at` |
18
18
  | `TextReveal`, `CountUp` with `at` | `at` |
19
19
  | `Steps` with `from` and `k` children (JSX elements, or one list with `k` items) | `from + k - 1` |
20
20
  | A fenced code block with `k` highlight steps and `at=<n>` | `at + k - 1` (see [code-blocks.md](code-blocks.md)) |
21
+ | A magic-move fence | `at` plus each version's highlight steps (at least 1 each), minus 1 (see [code-blocks.md](code-blocks.md)) |
21
22
 
22
23
  So this slide has two clicks with no `clicks:` line:
23
24
 
@@ -157,6 +158,29 @@ Draws the strokes of its SVG shape children on click `at`. It renders a `<g>`, s
157
158
 
158
159
  Props: `at`, `until`.
159
160
 
161
+ ### `Mark`
162
+
163
+ Draws a hand-drawn mark around inline text on click `at`, and removes it at `until`. The text is always visible and readable; only the mark comes and goes. Going back un-draws it.
164
+
165
+ ```mdx
166
+ The fix was <Mark kind="circle" at={1}>one line</Mark>, and <Mark at={2}>nobody</Mark> had read it.
167
+ ```
168
+
169
+ Props: `at`, `until`, `kind` and `color`.
170
+
171
+ | `kind` | Draws |
172
+ | --- | --- |
173
+ | `underline` (default) | A line under the text. |
174
+ | `circle` | An ellipse around it. |
175
+ | `box` | A rectangle around it. |
176
+ | `strike` | A line through its middle. |
177
+ | `cross` | Two diagonals across it. |
178
+ | `bracket` | A bracket either side. |
179
+
180
+ `color` takes any CSS colour, including a theme token (`color="var(--accent)"`); the default is the text colour. Set the stroke width with the `--deck-mark-width` CSS variable (default `3px`). The strokes come from [Rough.js](https://roughjs.com) with a fixed seed, so the same mark looks the same on every load and in every view. A mark over text that wraps onto two lines surrounds the whole box, and an `underline` sits under the last line only, so keep marked phrases short.
181
+
182
+ `Mark` is the counterpart of Slidev's `v-mark`.
183
+
160
184
  ## Hooks
161
185
 
162
186
  ### `useStepState(at, until?)`
@@ -1,6 +1,6 @@
1
1
  # Presenting
2
2
 
3
- Open the deck's URL, press `f` for fullscreen and use the arrow keys. Press `p` for a presenter window with notes, and `o` for an overview of every slide.
3
+ Open the deck's URL, press `f` for fullscreen and use the arrow keys. Press `p` for a presenter window with notes, `o` for an overview of every slide, and `g` to jump to a slide by number or title. Everything the keys do is also on the control tray in the bottom-left corner.
4
4
 
5
5
  ## Keyboard
6
6
 
@@ -23,6 +23,7 @@ Views and display:
23
23
  | `o` | Open the overview, or close it. | Every view. |
24
24
  | `Escape` | Close the overview without moving. | The overview. |
25
25
  | `p` | Open the presenter window. | The play view, when not embedded. |
26
+ | `g` | Open the go-to dialog. | The play view and presenter window, when not embedded or in the site player. |
26
27
  | `Cmd/Ctrl` + `+` or `=` | Larger slide text. | Play view and presenter window. |
27
28
  | `Cmd/Ctrl` + `-` | Smaller slide text. | Play view and presenter window. |
28
29
  | `Cmd/Ctrl` + `0` | Slide text back to its authored size. | Play view and presenter window. |
@@ -31,6 +32,20 @@ In the overview the arrow keys move between tiles instead: `ArrowRight` and `Arr
31
32
 
32
33
  Keys are ignored while typing in an input, textarea, select or editable element, and a held key acts once. `Space` and `Enter` on a focused button do the button's job, so after clicking "Reset timer" the arrow keys still advance the talk.
33
34
 
35
+ ## Control tray
36
+
37
+ Move the pointer to the bottom-left corner of the play view and a row of controls appears: previous, next, the position ("3 / 12", which opens the go-to dialog), overview, presenter, fullscreen and smaller or larger text. It fades out again when the pointer leaves, and `Tab` reaches it from the keyboard. Previous and next are disabled at the first and last click of the deck, and the fullscreen button is absent where the browser does not allow fullscreen.
38
+
39
+ Moving the pointer away also releases a clicked tray button's focus, so `Space` advances the talk again rather than pressing the button. The tray is not shown in the presenter window, the overview, print, or a deck running `?embedded`.
40
+
41
+ During a slide transition the browser routes clicks to the transition's snapshot, so a tray click in that moment is dropped. Keys still work; wait for the transition to finish or use the keyboard.
42
+
43
+ ## Go to a slide
44
+
45
+ Press `g`, or click the position in the tray. Type a number to pick that slide, or any other text to filter slides by title; `ArrowUp` and `ArrowDown` move the selection and `Enter` goes there, at click 0. `Escape` or a click outside closes the dialog without moving. A search that is only digits always means a slide number, so a title such as "2026" is found by another word in it.
46
+
47
+ In a synced talk, going to a slide from the presenter window moves the audience window too, as any other navigation does.
48
+
34
49
  ## The URL
35
50
 
36
51
  The position is in the URL hash, so a reload, a bookmark or a shared link lands on the same state.
package/docs/slides.md CHANGED
@@ -92,8 +92,9 @@ Every slide can use these names with no import.
92
92
  | Source | Names |
93
93
  | --- | --- |
94
94
  | The deck's `components/*.tsx` | Every named export under its own name; a default export under the file's basename. |
95
- | Motion (`@steamfield/decks/motion`) | `Step`, `Steps`, `Stagger`, `TextReveal`, `Highlight`, `CountUp`, `Draw`, `Morph` |
95
+ | Motion (`@steamfield/decks/motion`) | `Step`, `Steps`, `Stagger`, `TextReveal`, `Highlight`, `CountUp`, `Draw`, `Morph`, `Mark` |
96
96
  | Layouts (`@steamfield/decks`) | `Center`, `Cover`, `Section`, `TwoCol`, `ImageSide` |
97
+ | Navigation (`@steamfield/decks`) | `Toc`, `Link` |
97
98
  | Built in | `Notes`; fenced code blocks render through `CodeBlock` |
98
99
 
99
100
  A deck component with the same name as a framework one replaces it for that deck. A replaced motion component no longer adds clicks.
@@ -121,6 +122,24 @@ slides/03-x.mdx:3:1: <Nonexistent> is not defined. Export it from a file in comp
121
122
 
122
123
  Lowercase elements and member names such as `<motion.div>` are not checked.
123
124
 
125
+ ## Links between slides
126
+
127
+ `<Link to={5}>the results</Link>` is a link to slide 5 at click 0. In the play view and the presenter window a click goes there, and in a synced talk the other windows follow. A `Cmd`- or `Ctrl`-click opens the slide in a new tab, which joins the talk's sync and then follows the talk's position. A `to` that is not a slide number in the deck is an error naming it.
128
+
129
+ `<Toc />` is an agenda: a numbered list of every slide's title as a `Link`, with the current slide marked (`aria-current="page"`). Slides without a `title` in their frontmatter are listed by number, and hidden slides are left out.
130
+
131
+ In the overview, a preview, and print, both render as plain text, so a thumbnail never navigates.
132
+
133
+ ```mdx
134
+ ---
135
+ title: What this talk covers.
136
+ ---
137
+
138
+ <h1>What this talk covers.</h1>
139
+
140
+ <Toc />
141
+ ```
142
+
124
143
  ## Built-in layouts
125
144
 
126
145
  Layouts arrange their children and nothing else. They set no fonts, colors or sizes. Each fills the slide and pads its content with `--deck-pad-x` (120px) and `--deck-pad-y` (96px); the gap between children is `--deck-gap` (80px). Override the variables in your CSS.