Skip to content

Commit 0751f4d

Browse files
authored
Try it: run the lesson on the playground's simulate view (#11)
* Try it: run the lesson on the playground's simulate view The lesson's widget was a small hand-made copy of the playground's simulate view. It's now that view, from comline-web-kit (a workspace of the playground repo) in its lesson layout: the Chat client and server from chat.lesson.json, the client's calls, the server's behaviours (reply, echo, drop) and the frame log, themed with the tutorial's palette. - comline-web-kit replaces the direct comline-simulator dependency; it depends on the simulator itself. CI skips the kit's editor WASM (COMLINE_KIT_EDITOR=0), as it skips the scripted engine. - Vite serves the kit as source (optimizeDeps.exclude), and TypeScript allows its .ts import paths. - The page says to click the server to change its behaviour. - A Playwright test sends a call, sees the reply and frames, switches the server to drop, and sees the next call time out. * Pin comline-web-kit to playground master
1 parent 732a023 commit 0751f4d

10 files changed

Lines changed: 253 additions & 247 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,10 @@ jobs:
4545
- name: Yarn
4646
run: corepack enable
4747

48-
# `comline-simulator` is a git dependency that compiles to WASM in its
49-
# `prepack` (Rust to wasm-bindgen). The image has cargo, wasm-bindgen and
50-
# wasm-opt; this caches the registry and git checkouts across runs.
48+
# `comline-web-kit` (the playground's simulate view) is a git dependency,
49+
# and so is its engine, `comline-simulator`, which compiles to WASM in
50+
# its `prepack` (Rust to wasm-bindgen). The image has cargo, wasm-bindgen
51+
# and wasm-opt; this caches the registry and git checkouts across runs.
5152
- name: Cache cargo
5253
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
5354
with:
@@ -57,8 +58,8 @@ jobs:
5758
key: ${{ runner.os }}-${{ runner.arch }}-cargo-${{ hashFiles('yarn.lock') }}
5859
restore-keys: ${{ runner.os }}-${{ runner.arch }}-cargo-
5960

60-
# Yarn Berry's global cache holds the built `comline-simulator`
61-
# archive: a hit skips the Rust build entirely.
61+
# Yarn Berry's global cache holds the packed `comline-web-kit` and the
62+
# built `comline-simulator` archives: a hit skips the Rust build entirely.
6263
- name: Cache yarn
6364
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
6465
with:
@@ -70,6 +71,7 @@ jobs:
7071
- name: Install dependencies
7172
env:
7273
COMLINE_SIMULATOR_SCRIPT: '0' # the tutorial only needs the lean sim
74+
COMLINE_KIT_EDITOR: '0' # and not the kit's editor WASM
7375
run: yarn install
7476

7577
- name: build

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,6 @@ vite.config.ts.timestamp-*
2121

2222
# JetBrains IDEA settings
2323
.idea/
24+
25+
# Playwright
26+
/test-results

‎.yarnrc.yml‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
yarnPath: .yarn/releases/yarn-4.18.0.cjs
22
nodeLinker: node-modules
33

4-
# `comline-simulator` is the sim engine — a git dep that builds itself to WASM
5-
# in its `prepack`/`prepare`. Yarn 4 gates git deps and disables scripts by
6-
# default; both are needed. The build is not byte-reproducible (wasm-opt runs
7-
# only where installed) so let Yarn refresh the tarball checksum.
4+
# `comline-web-kit` (the playground's simulate view, a workspace of the
5+
# playground repo) and `comline-simulator` (its engine) are git deps that
6+
# build in their `prepack`. Yarn 4 gates git deps and disables scripts by
7+
# default; both are needed. The builds are not byte-reproducible (wasm-opt
8+
# runs only where installed) so let Yarn refresh the tarball checksums.
89
approvedGitRepositories:
10+
- "https://github.com/ComlineProject/playground.git"
911
- "https://github.com/ComlineProject/simulator.git"
1012
enableScripts: true
1113
checksumBehavior: update

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@
3636
"type": "module",
3737
"dependencies": {
3838
"@sveltejs/adapter-static": "^3.0.10",
39-
"comline-simulator": "git+https://github.com/ComlineProject/simulator.git#1eab1f84f1ae7760135ca4a7a519c78091001a44"
39+
"comline-web-kit": "git+https://github.com/ComlineProject/playground.git#workspace=comline-web-kit&commit=fe53d2edcd25cf8bcd77d9f52a3c2ec09d453136"
4040
},
4141
"resolutions": {
4242
"cookie": "^0.7.2",

‎src/lib/sim/Simulation.svelte‎

Lines changed: 47 additions & 226 deletions
Original file line numberDiff line numberDiff line change
@@ -1,246 +1,67 @@
11
<script lang="ts">
2-
import { onMount, onDestroy } from 'svelte';
3-
import init, { Sim } from 'comline-simulator';
4-
import wasmUrl from 'comline-simulator/pkg/comline_simulator_bg.wasm?url';
2+
// The "Try it" lesson: the playground's simulate view (comline-web-kit) in
3+
// its lesson layout, on the Chat client and server that chat.lesson.json
4+
// wires together. It opens on the client's calls; clicking the server
5+
// shows what it answers `send` with.
6+
import { createSim, loadSim, type ProjectShape, type SimView } from 'comline-web-kit/sim';
7+
import 'comline-web-kit/sim.css';
58
import lesson from '$lib/sim/lessons/chat.lesson.json';
69
7-
interface Frame {
8-
seq: number;
9-
from: string;
10-
to: string;
11-
bytes: number[];
12-
at: number;
13-
kind: string;
14-
}
15-
interface Instance {
16-
id: string;
17-
name: string;
18-
role: 'client' | 'server';
19-
protocol: string;
20-
behaviors: Record<string, { kind: string }>;
21-
}
22-
interface Model {
23-
instances: Instance[];
24-
connections: { id: string; clientId: string; serverId: string }[];
25-
}
26-
27-
const BEHAVIOURS = [
28-
{ kind: 'reply', label: 'reply (a default Message)' },
29-
{ kind: 'echo', label: 'echo (bounce the request back)' },
30-
{ kind: 'drop', label: 'drop (never answer)' }
31-
];
32-
33-
let sim: Sim | null = null;
34-
let model = $state<Model | null>(null);
35-
let frames = $state<Frame[]>([]);
36-
let text = $state('hello');
37-
let result = $state<string | null>(null);
38-
let busy = $state(false);
10+
let loading = $state(true);
3911
let error = $state<string | null>(null);
4012
41-
const client = $derived(model?.instances.find((i) => i.role === 'client') ?? null);
42-
const server = $derived(model?.instances.find((i) => i.role === 'server') ?? null);
43-
const conn = $derived(model?.connections[0] ?? null);
44-
const behaviour = $derived(server?.behaviors['send']?.kind ?? 'reply');
45-
46-
function refresh() {
47-
if (!sim) return;
48-
model = JSON.parse(sim.session_json()) as Model;
49-
const c = model.connections[0];
50-
frames = c ? (JSON.parse(sim.frames(c.id)) as Frame[]) : [];
51-
}
52-
53-
function setBehaviour(kind: string) {
54-
if (!sim || !server) return;
55-
sim.set_behavior(server.id, 'send', kind, '{}');
56-
result = null;
57-
refresh();
58-
}
59-
60-
function send() {
61-
if (!sim || !conn || busy) return;
62-
busy = true;
63-
result = null;
64-
try {
65-
const id = sim.call(conn.id, 'send', JSON.stringify({ text }));
66-
// canned behaviours settle fast; the cap also covers `drop` → timeout
67-
for (let i = 0; i < 400 && sim.pending() > 0; i++) sim.advance(25);
68-
const raw = sim.result(id);
69-
const r = raw ? (JSON.parse(raw) as Record<string, unknown>) : null;
70-
result =
71-
r === null
72-
? 'still in flight'
73-
: r.status === 'ok'
74-
? `reply · ${JSON.stringify(r.value)}`
75-
: r.status === 'err'
76-
? `error ${r.ordinal} · ${JSON.stringify(r.body)}`
77-
: r.status === 'timeout'
78-
? 'timed out — no reply came back'
79-
: String(r.status);
80-
} finally {
81-
busy = false;
82-
refresh();
83-
}
13+
/** Mounts the view into `host` once its engine has loaded. */
14+
function simulation(host: HTMLElement) {
15+
let view: SimView | null = null;
16+
let gone = false;
17+
loadSim()
18+
.then(() => {
19+
if (gone) return;
20+
view = createSim({
21+
layout: 'lesson',
22+
behaviours: ['reply', 'echo', 'drop'],
23+
select: 'chat-2'
24+
});
25+
host.append(view.el);
26+
view.setShape(lesson.shape as ProjectShape, lesson.session);
27+
})
28+
.catch((e) => {
29+
error = `could not start the simulation · ${(e as Error).message ?? e}`;
30+
})
31+
.finally(() => {
32+
loading = false;
33+
});
34+
return {
35+
destroy() {
36+
gone = true;
37+
view?.destroy();
38+
}
39+
};
8440
}
85-
86-
onMount(async () => {
87-
try {
88-
await init({ module_or_path: wasmUrl });
89-
sim = new Sim(JSON.stringify(lesson.shape), lesson.session);
90-
sim.set_call_timeout(2000);
91-
refresh();
92-
} catch (e) {
93-
error = `could not start the simulation · ${(e as Error).message ?? e}`;
94-
}
95-
});
96-
97-
onDestroy(() => sim?.free());
9841
</script>
9942

100-
<div class="sim">
43+
<div class="lesson-sim">
10144
{#if error}
10245
<p class="err">{error}</p>
103-
{:else if !model}
46+
{:else if loading}
10447
<p class="muted">loading the simulation…</p>
105-
{:else}
106-
<div class="wire">
107-
<div class="node client">{client?.name ?? 'client'}<span>{client?.protocol} client</span></div>
108-
<div class="link" class:dropping={behaviour === 'drop'}></div>
109-
<div class="node server">{server?.name ?? 'server'}<span>{server?.protocol} server</span></div>
110-
</div>
111-
112-
<label class="ctl">
113-
server answers <code>send</code> with
114-
<select value={behaviour} onchange={(e) => setBehaviour(e.currentTarget.value)}>
115-
{#each BEHAVIOURS as b (b.kind)}
116-
<option value={b.kind}>{b.label}</option>
117-
{/each}
118-
</select>
119-
</label>
120-
121-
<form
122-
class="ctl call"
123-
onsubmit={(e) => {
124-
e.preventDefault();
125-
send();
126-
}}
127-
>
128-
<code>send</code>(<input bind:value={text} aria-label="text argument" />)
129-
<button type="submit" disabled={busy}>send</button>
130-
</form>
131-
132-
{#if result}
133-
<p class="result">{result}</p>
134-
{/if}
135-
136-
<ol class="frames">
137-
{#each frames as f (f.seq)}
138-
<li>
139-
<span class="seq">{String(f.seq).padStart(2, '0')}</span>
140-
<span class="dir">{f.from} → {f.to}</span>
141-
<span class="kind">{f.kind}</span>
142-
<span class="len">{f.bytes.length} B</span>
143-
</li>
144-
{:else}
145-
<li class="muted">no frames yet — send a call</li>
146-
{/each}
147-
</ol>
14848
{/if}
49+
<div use:simulation></div>
14950
</div>
15051

15152
<style>
152-
.sim {
153-
width: min(100%, 32rem);
53+
/* The tutorial's palette, for the view's --cl-* properties. */
54+
.lesson-sim {
55+
--cl-bg: #1a1714;
56+
--cl-bg-2: #322922;
57+
--cl-fg: #f2e1ca;
58+
--cl-muted: #a8927a;
59+
--cl-accent: #dbb594;
60+
--cl-border: #614a39;
61+
62+
width: min(100%, 40rem);
15463
margin: 1rem auto;
155-
padding: 0.9rem;
15664
text-align: left;
157-
border-style: ridge;
158-
border-color: #614a39;
159-
}
160-
.wire {
161-
display: flex;
162-
align-items: center;
163-
gap: 0.5rem;
164-
margin-bottom: 0.9rem;
165-
}
166-
.node {
167-
flex: 1;
168-
display: flex;
169-
flex-direction: column;
170-
align-items: center;
171-
padding: 0.5rem;
172-
background-color: #322922;
173-
color: #dbb594;
174-
border-style: ridge;
175-
border-color: #4d3c2f;
176-
}
177-
.node span {
178-
font-size: 0.75rem;
179-
opacity: 0.7;
180-
}
181-
.link {
182-
flex: 0 0 2.5rem;
183-
height: 2px;
184-
background: #dbb594;
185-
}
186-
.link.dropping {
187-
background: repeating-linear-gradient(90deg, #dbb594 0 4px, transparent 4px 8px);
188-
}
189-
.ctl {
190-
display: block;
191-
margin: 0.5rem 0;
192-
}
193-
.ctl.call {
194-
display: flex;
195-
align-items: center;
196-
gap: 0.3rem;
197-
flex-wrap: wrap;
198-
}
199-
.ctl input {
200-
flex: 1;
201-
min-width: 6rem;
202-
}
203-
select,
204-
input,
205-
button {
206-
font: inherit;
207-
}
208-
button {
209-
padding: 0.2rem 0.8rem;
210-
background-color: #322922;
211-
color: #dbb594;
212-
border-color: #4d3c2f;
213-
border-style: ridge;
214-
cursor: pointer;
215-
}
216-
button:disabled {
217-
opacity: 0.5;
218-
cursor: default;
219-
}
220-
.result {
221-
margin: 0.5rem 0;
222-
padding: 0.4rem 0.6rem;
223-
background: #2a211d;
224-
color: #dbb594;
225-
}
226-
.frames {
227-
list-style: none;
228-
margin: 0.6rem 0 0;
229-
padding: 0;
230-
font-size: 0.85rem;
231-
}
232-
.frames li {
233-
display: flex;
234-
gap: 0.6rem;
235-
padding: 0.15rem 0;
236-
border-top: 1px solid #4d3c2f;
237-
}
238-
.frames .seq {
239-
opacity: 0.6;
240-
}
241-
.frames .len {
242-
margin-left: auto;
243-
opacity: 0.6;
24465
}
24566
.muted {
24667
opacity: 0.6;

‎src/routes/part-1_introduction/sect-3_try-it/+page.svelte‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,18 +7,19 @@
77
<TutorialPage previous_url={pageUrl('p1-s2')} next_url={pageUrl('p1-s4')}>
88
<h2>Try it</h2>
99
<p>
10-
Below is a Chat client and server, both generated from the same schema and wired together. Send a
11-
call and watch it serialise, cross the connection, get dispatched, and come back.
10+
Below is a Chat client and server, both generated from the same schema and wired together. Send
11+
a call from the client and watch it serialise, cross the connection, get dispatched, and come
12+
back.
1213
</p>
1314
<p>
14-
Change what the server does with <code>send</code> — reply, echo the request straight back, or
15-
drop it and let the client time out.
15+
Click the server to change what it does with <code>send</code>: reply, echo the request straight
16+
back, or drop it and let the client time out.
1617
</p>
1718

1819
<Simulation />
1920

2021
<p>
21-
This is the real runtime: the same framing, envelope and dispatch the generated code uses, run in
22-
your browser as WebAssembly.
22+
This is the real runtime: the same framing, envelope and dispatch the generated code uses, run
23+
in your browser as WebAssembly.
2324
</p>
2425
</TutorialPage>

0 commit comments

Comments
 (0)