@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.
- package/dist/cli.js +1 -1
- package/dist/control-tray.css +84 -0
- package/dist/go-to-dialog.css +57 -0
- package/dist/{index-BURtH7IB.d.ts → index-D3Yj4yT6.d.ts} +11 -2
- package/dist/{index-BV_-6L5L.d.ts → index-DG8UcGQd.d.ts} +77 -1
- package/dist/{index-B2n69xrC.d.ts → index-zg-z6HTy.d.ts} +18 -2
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2 -2
- package/dist/kit/term/live-term.module.css +36 -0
- package/dist/kit.d.ts +21 -6
- package/dist/kit.js +252 -8
- package/dist/live-term.module.css +36 -0
- package/dist/magic-move.css +30 -0
- package/dist/mark.css +34 -0
- package/dist/motion.d.ts +2 -2
- package/dist/motion.js +1 -1
- package/dist/node.d.ts +5 -1
- package/dist/node.js +1 -1
- package/dist/plugin/skills/building-a-deck/references/workflow.md +10 -0
- package/dist/plugin/skills/deck-design/references/layout.md +2 -0
- package/dist/plugin/skills/deck-motion/references/motion.md +38 -1
- package/dist/plugin/skills/working-with-decks/references/project.md +4 -0
- package/dist/presenter-view.css +14 -0
- package/dist/{prose-patterns-DPqjGBFu.js → prose-patterns-D-tdt0Ab.js} +3 -1
- package/dist/{prose-scan-BrWZ7gxZ.js → prose-scan-ni8g6pc-.js} +2 -2
- package/dist/{src-DizFoqYt.js → src--lhAQ29p.js} +348 -43
- package/dist/{src-C-OfT72W.js → src-BNyL3q7j.js} +212 -3
- package/dist/{src-CmQgaG1b.js → src-Cxck-eLP.js} +588 -68
- package/dist/term/shell_pty.py +38 -0
- package/dist/term/zsh/.zshrc +4 -0
- package/dist/term-protocol-B_qHRDEp.js +11 -0
- package/dist/xterm-host-C6OjffSm.js +282 -0
- package/docs/README.md +1 -0
- package/docs/cli.md +2 -1
- package/docs/code-blocks.md +31 -0
- package/docs/config.md +1 -0
- package/docs/getting-started.md +2 -1
- package/docs/kit.md +7 -6
- package/docs/migrating-from-slidev.md +4 -0
- package/docs/motion.md +25 -1
- package/docs/presenting.md +16 -1
- package/docs/slides.md +20 -1
- package/docs/terminal.md +97 -0
- package/package.json +4 -1
package/docs/terminal.md
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# Live terminal
|
|
2
|
+
|
|
3
|
+
`LiveTerm` puts a real shell on a slide. Each click on the slide types the next command into it and runs it, so a talk about a command-line tool never leaves the deck. Everywhere a shell can't run (a built deck, `decks export`, the presenter's preview, the overview, a dev server started without `--live-term`), the pane shows a fallback you supply instead, usually a recording of the same commands.
|
|
4
|
+
|
|
5
|
+
It works on macOS and Linux. The shell is `zsh`, run through Python's standard `pty` module, so both must be on the speaker's machine. On Windows the dev server logs one line and every pane shows its fallback.
|
|
6
|
+
|
|
7
|
+
## A pane
|
|
8
|
+
|
|
9
|
+
```tsx
|
|
10
|
+
// components/Demo.tsx
|
|
11
|
+
import { useSlide } from "@steamfield/decks";
|
|
12
|
+
import { LiveTerm } from "@steamfield/decks/kit";
|
|
13
|
+
|
|
14
|
+
const pane = {
|
|
15
|
+
id: "hello",
|
|
16
|
+
rows: 12,
|
|
17
|
+
cols: 60,
|
|
18
|
+
cwd: "temp",
|
|
19
|
+
commands: ["echo hello", "ls", "git status"],
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
export function Demo() {
|
|
23
|
+
const { clicks } = useSlide();
|
|
24
|
+
return (
|
|
25
|
+
<LiveTerm
|
|
26
|
+
pane={pane}
|
|
27
|
+
click={clicks}
|
|
28
|
+
fallback={<pre>{RECORDING.slice(0, clicks + 1).join("\n")}</pre>}
|
|
29
|
+
/>
|
|
30
|
+
);
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The slide sets `clicks:` in its frontmatter to the number of commands. Moving from click n − 1 to n types `commands[n - 1]` and runs it; returning to click 0 restarts the shell.
|
|
35
|
+
|
|
36
|
+
| `pane` field | Meaning |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| `id` | Unique in the deck. One shell runs per id, shared by every window showing it. |
|
|
39
|
+
| `rows`, `cols` | The fixed grid. The font is sized to fill the pane with whole-pixel glyphs; the grid never reflows. |
|
|
40
|
+
| `cwd` | `"temp"` for a fresh temporary directory, or a key of `term.dirs` in `deck.config.ts`. Any other value is an error naming the pane. |
|
|
41
|
+
| `commands` | The commands, one per click. |
|
|
42
|
+
|
|
43
|
+
Run it live with `decks dev <deck> --live-term`. The pane goes live when it is in the play view, its slide is the current one, the deck is not embedded and motion is not `instant`. It stays on its fallback otherwise.
|
|
44
|
+
|
|
45
|
+
## Working directories
|
|
46
|
+
|
|
47
|
+
A pane that should run in a real project names it through the config:
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
export default defineDeck({
|
|
51
|
+
title: "Agents",
|
|
52
|
+
term: { dirs: { repo: "../.." } },
|
|
53
|
+
});
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Paths are relative to the deck directory. The browser only ever sends the key (`cwd: "repo"`), never a path. Every command checks that `dirs` is a record of strings. Only `decks dev --live-term` checks that each directory exists, since a deck built on another machine names directories that only exist on the speaker's.
|
|
57
|
+
|
|
58
|
+
## Styling and status
|
|
59
|
+
|
|
60
|
+
The kit ships no terminal skin. The pane reads `--deck-term-font`, `--deck-term-font-size`, `--deck-term-foreground` and `--deck-term-background` from CSS. Without `frame`, a pane that fell back after trying to go live shows the reason below its fallback in a `role="status"` element. With `frame`, you draw that yourself:
|
|
61
|
+
|
|
62
|
+
```tsx
|
|
63
|
+
<LiveTerm
|
|
64
|
+
pane={pane}
|
|
65
|
+
click={clicks}
|
|
66
|
+
fallback={recording}
|
|
67
|
+
frame={(content, status) => (
|
|
68
|
+
<figure className={styles.window}>
|
|
69
|
+
{content}
|
|
70
|
+
<figcaption>
|
|
71
|
+
{status.live ? "Live" : "Recorded"}
|
|
72
|
+
{status.queued ? " · queued" : status.busy ? " · busy" : ""}
|
|
73
|
+
{status.reason && ` · ${status.reason}`}
|
|
74
|
+
</figcaption>
|
|
75
|
+
</figure>
|
|
76
|
+
)}
|
|
77
|
+
/>
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`status` is `{ live, busy, queued, reason? }`: the shell is on screen, a command is running, clicks are waiting for a prompt, and why the pane fell back. The fallback stays visible until the shell has drawn its first prompt, so the slide never shows an empty pane.
|
|
81
|
+
|
|
82
|
+
## While presenting
|
|
83
|
+
|
|
84
|
+
A click into the pane gives it the keyboard; `Escape` gives the keys back to the deck. Pressing next while a command still runs queues the next command until the prompt returns. Every audience window shows the same shell, and each command runs once whichever window advanced, the presenter included. The presenter's own preview of the slide shows the fallback. Reloading a window reattaches to the running shell and replays its recent output. If the shell exits or its connection drops, the pane goes back to its fallback with the reason.
|
|
85
|
+
|
|
86
|
+
The dev server only starts shells when it listens on a loopback address, its hot-update socket shares the page's port, and Vite's socket token and Host checks are on. A deck's `vite` config that changes any of these turns the terminal off with a line in the dev log saying why. None of the checks can be turned off: anything that can reach the socket can type into the shell.
|
|
87
|
+
|
|
88
|
+
## Limits
|
|
89
|
+
|
|
90
|
+
- A full-screen program (`vim`, `htop`, a TUI) is not supported. A reattach replays the tail of the output, which redraws such a program wrongly.
|
|
91
|
+
- Jumping back to a terminal slide at click 0 from far away (the go-to dialog, the overview) replays the old session instead of restarting the shell. Step to click 1 and back to restart it.
|
|
92
|
+
- If the dev server restarts while a pane is past click 0, later commands wait until the pane returns to click 0.
|
|
93
|
+
- A next pressed before the terminal slide has appeared on the first load moves the click without running its command, and later commands then wait until click 0. Wait for the slide before advancing.
|
|
94
|
+
- Typing into a focused pane during the short pause before a command's Enter is sent edits that command.
|
|
95
|
+
- Windows order their reports by the deck's sync stamp, which two separate browsers (or a private window) don't share. Keep every window of one talk in the same browser profile.
|
|
96
|
+
- Reloading a window can, rarely, leave its pane ignoring clicks, if the old page's connection closes after the reloaded page has reconnected. Close every window showing the deck and open it again.
|
|
97
|
+
- After editing a pane's spec in dev, a stale hot update can briefly restart the pane with the old spec; saving again restores the new one.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@steamfield/decks",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "React slide decks for animated, data-driven talks: MDX slides, motion, story stages, charts, and a CLI, built with coding agents.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -66,10 +66,12 @@
|
|
|
66
66
|
"@mdx-js/rollup": "3.1.1",
|
|
67
67
|
"@opendata-ai/openchart-core": "9.0.0",
|
|
68
68
|
"@opendata-ai/openchart-react": "9.0.0",
|
|
69
|
+
"@shikijs/magic-move": "4.6.0",
|
|
69
70
|
"@shikijs/rehype": "4.6.0",
|
|
70
71
|
"@types/d3-scale": "4.0.9",
|
|
71
72
|
"@types/mdx": "2.0.14",
|
|
72
73
|
"@vitejs/plugin-react": "6.3.0",
|
|
74
|
+
"@xterm/xterm": "6.0.0",
|
|
73
75
|
"citty": "0.2.2",
|
|
74
76
|
"d3-scale": "4.0.2",
|
|
75
77
|
"get-port": "7.2.0",
|
|
@@ -85,6 +87,7 @@
|
|
|
85
87
|
"remark-mdx": "3.1.1",
|
|
86
88
|
"remark-parse": "11.0.0",
|
|
87
89
|
"remark-rehype": "11.1.2",
|
|
90
|
+
"roughjs": "4.6.6",
|
|
88
91
|
"shiki": "4.6.0",
|
|
89
92
|
"three": "0.185.1",
|
|
90
93
|
"three-spritetext": "1.10.0",
|