create-acrylblends 1.0.10 → 1.2.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/index.d.ts +5 -0
- package/dist/index.js +171 -8
- package/dist/index.js.map +1 -1
- package/docs/framework/agents/index.md +1 -1
- package/docs/framework/api/summary.md +1 -1
- package/docs/framework/getting-started/desktop.md +23 -4
- package/docs/framework/guides/create-acrylblends.md +1 -1
- package/docs/framework/guides/production.md +20 -0
- package/docs/framework/workshop/README.md +174 -285
- package/docs/framework/workshop/facilitator.md +81 -90
- package/package.json +2 -2
|
@@ -1,108 +1,99 @@
|
|
|
1
|
-
# Facilitator notes: the
|
|
1
|
+
# Facilitator notes: building inside the ACRYL frame
|
|
2
2
|
|
|
3
|
-
Read the
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Read the handout first (`docs/framework/workshop/README.md`); this page is the room around it. The workshop changed shape again for the frame: the
|
|
4
|
+
app is created, then **opened inside ACRYL's IDE** (projects on the left, the app's page in the canvas, files/changes/terminals on the right), a
|
|
5
|
+
chat model works on the app from inside the frame, and coding agents run in terminal tabs in the same folder. The data layer, the desktop window and
|
|
6
|
+
the panel-first flow of the previous handout are gone.
|
|
7
|
+
|
|
8
|
+
The handout is written for **acrylblends 1.2.0 or newer** (the release that carries the frame). A room on an older release is on the previous handout;
|
|
9
|
+
check with `npx acrylblends@latest --version` before the day.
|
|
6
10
|
|
|
7
11
|
## Before the room: put this on every machine
|
|
8
12
|
|
|
9
13
|
| What | Why | How |
|
|
10
14
|
| --- | --- | --- |
|
|
11
|
-
|
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
15
|
-
|
|
|
16
|
-
| A
|
|
17
|
-
| A
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
## Timings, checkpoints, and what to make optional
|
|
32
|
-
|
|
33
|
-
The handout's own timings, as measured on the published 1.0.2 (macOS, cold npm cache in a throwaway home):
|
|
34
|
-
|
|
35
|
-
| Minutes | Step | Measured | If late |
|
|
15
|
+
| The preflight passing | it checks Node, npm, git, an agent with its login or key, a free port, and on Windows PowerShell and long paths | `npx acrylblends@latest preflight` ends with `Ready for the workshop.` |
|
|
16
|
+
| Node.js 22.19 or newer (24 and 26 tested) | the app runs TypeScript directly | `node -v`; the app's `scripts/check-node.cjs` refuses an older Node with a clear line |
|
|
17
|
+
| git, and a GitHub account with `gh auth login` | the first `npm run dev` makes the folder a git repository (Files and Changes need one); the last block forks the registry | `git --version`, `gh auth status` |
|
|
18
|
+
| One coding agent, logged in | block 5 starts it in a terminal tab; `claude`, `codex` and `pi` all worked | `codex login` once, or run `claude` once, or pi with `DEEPSEEK_API_KEY` in the terminal that starts `npm run dev` |
|
|
19
|
+
| One model key | block 3 adds it in Settings > Models; without it the chat shows a connect card | a DeepSeek key from <https://platform.deepseek.com>, or a Claude/ChatGPT subscription through Sign in with an account |
|
|
20
|
+
| A prepared app with `npm install` done | the first install brings the frame and the chat engine (about 500 MB together); a room on one Wi-Fi should not do it 20 times | run the handout's block 1 once per machine and keep the folder as `~/acryl-workshop/prepared/` |
|
|
21
|
+
| A warm npm cache | the first install dominates block 1 | the prepared app does it |
|
|
22
|
+
|
|
23
|
+
**The agent setting that decides the day.** The agents are configured to act rather than describe. Check on every machine that a plain request
|
|
24
|
+
produces files, not a plan: ask the prepared app's chat "add a line to the app's page" and watch the Changes panel. If it only describes, the model
|
|
25
|
+
is waiting for permission; the handout's sentence is "do it now".
|
|
26
|
+
|
|
27
|
+
**Agent-specific checks.** Codex answering `model_not_found` means the account does not have the default model: pick one it supports (`/model` in
|
|
28
|
+
codex, or `model = "..."` in `~/.codex/config.toml`). pi with DeepSeek needs `DEEPSEEK_API_KEY` in the environment of the terminal that runs `npm
|
|
29
|
+
run dev` (the terminal tabs inherit it); the preflight reports `PASS agent pi (DeepSeek key found)`. The package is
|
|
30
|
+
`@earendil-works/pi-coding-agent`.
|
|
31
|
+
|
|
32
|
+
## Timings, from the rehearsal (this Mac, packed CLI, isolated HOME)
|
|
33
|
+
|
|
34
|
+
| Minutes | Block | Measured | If late |
|
|
36
35
|
| --- | --- | --- | --- |
|
|
37
|
-
| 0-10 |
|
|
38
|
-
| 10-
|
|
39
|
-
|
|
|
40
|
-
|
|
|
41
|
-
| 30-
|
|
42
|
-
|
|
|
43
|
-
|
|
|
44
|
-
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
- **
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
- **Browser-only attendees (TODO(M9)).** The handout's hosted-workspace stub is empty until M9 is live; until then a browser-only attendee can follow
|
|
71
|
-
along but not create an app.
|
|
72
|
-
- **node-pty's install script (C5).** `npm install` warns that npm 11 blocked `node-pty`'s script. The terminal drivers still list; the workshop does
|
|
73
|
-
not open one.
|
|
36
|
+
| 0-10 | preflight and setup | preflight ~15 s; the prepared app skips create and install | never cut |
|
|
37
|
+
| 10-20 | create and open the frame | the first `npm install` dominates (the frame and the chat engine); the frame's first page is up in a few seconds after that | use the prepared app and open its frame |
|
|
38
|
+
| 20-25 | the first change at /app | the Files view opens `src/routes.ts`; stop and `npm run dev` reconnects the frame in a few seconds; the page shows the edit | cut `npm test` to the take-home |
|
|
39
|
+
| 25-30 | Settings > Models | the key saves with Apply (`Saved DeepSeek (deepseek-official).`); the page uses it after a reload | paste the key in the first-run card instead, Save and continue |
|
|
40
|
+
| 30-50 | chat builds the board | the chat writes into the app folder and Changes fills; the restart loop shows it at /app/board | if the model is slow, cut the board to one column |
|
|
41
|
+
| 50-65 | a coding agent in a terminal | the agent tab starts in the app folder (its prompt is `my-app`); `.acryl/bin/acryl look` prints the page in the frame's tile | demo one agent and let the room follow |
|
|
42
|
+
| 65-80 | upgrade an older app | `npx acrylblends@latest upgrade` reports every file it changed (the `frame` line is the new layout), then `npm install` and `npm run dev` | keep the report, skip the second app |
|
|
43
|
+
| 80-90 | publish (take-home) | the registry check merges in about two minutes | leave it as the take-home |
|
|
44
|
+
|
|
45
|
+
What the rehearsal verified end to end on this Mac: a packed CLI in an isolated HOME, the app opened by the frame with the app's page in a tab
|
|
46
|
+
(the first-run tile), the Preview Notice dismissed once, Settings > Models saving a key and the chat sending with it (against a local mock), a
|
|
47
|
+
terminal tab running commands in the app folder, the app's page edited and shown after a restart, the door seeing the page (`acryl look`), and an
|
|
48
|
+
app made by the previous release upgraded and opened by the frame.
|
|
49
|
+
|
|
50
|
+
## What to say in the room
|
|
51
|
+
|
|
52
|
+
- **The frame is the product.** The point is not "an app with a chat sidebar"; it is that ACRYL's IDE hosts the app you are building: the app is
|
|
53
|
+
the page in the middle, its folder is the workspace, and the agents work in that folder.
|
|
54
|
+
- **Settings > Models is the key's home.** The key goes to the frame's own credentials store, never the app folder or `.acrylblends` files. The
|
|
55
|
+
first-run card writes the same store; either path is fine.
|
|
56
|
+
- **The loop is stop, start, look.** A source change needs `npm run dev` again; the port is stable per app, so the frame reconnects on the same
|
|
57
|
+
address and the app's tab is still there. If a chat tab comes to the front after the restart, press the `my-app` tab.
|
|
58
|
+
- **Two kinds of agent.** The chat (DSH's own, in the frame) and the coding agents in terminal tabs are different hands on the same folder; show
|
|
59
|
+
both and let people pick.
|
|
60
|
+
- **The door.** `.acryl/bin/acryl look` prints the page with refs, `act` clicks and types. In the frame the page is the tile, and the door sees
|
|
61
|
+
it. This is how an agent checks its own work.
|
|
62
|
+
- **Production is unchanged.** The frame, the chat and the agents are development tools; `NODE_ENV=production npm start` serves the app alone.
|
|
63
|
+
|
|
64
|
+
## Windows
|
|
65
|
+
|
|
66
|
+
Windows PowerShell 5.1 has no `&&` (two lines, or `;`); PowerShell sets variables with `$env:NAME="value"`; cmd.exe's `Ctrl-C` asks `Terminate
|
|
67
|
+
batch job (Y/N)?` (answer `Y`); cmd.exe does not expand `~` (use `%USERPROFILE%`). `npm install` needs the "Desktop development with C++" workload
|
|
68
|
+
of Visual Studio Build Tools for the terminal package; the preflight notes it.
|
|
74
69
|
|
|
75
70
|
## The no-network fallback
|
|
76
71
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
2. Step 8 uses the cloned registry and the installed `blends-core`; no network needed.
|
|
81
|
-
3. Step 7 needs the agent's own model, so it cannot run offline. Demo it from your machine on a tethered connection, or record it (a 4-minute
|
|
82
|
-
screen recording of the codex run is enough).
|
|
83
|
-
4. Keep one machine on a phone hotspot for `npm create` failures.
|
|
72
|
+
1. Prepared apps with `npm install` done cover blocks 1, 2 and the frame; the models (chat and agents) still need a connection or a demo.
|
|
73
|
+
2. Block 7's registry needs GitHub; if the venue is offline, publish from your machine on a hotspot at the end, or show the recording.
|
|
74
|
+
3. Keep one phone hotspot for the room.
|
|
84
75
|
|
|
85
|
-
## Demo script
|
|
76
|
+
## Demo script (five minutes, if the room is behind)
|
|
86
77
|
|
|
87
|
-
1.
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
78
|
+
1. Prepared app, frame open on the app's page: press `+`, open **AcrylDSH Chat**, ask for a sentence on the page. Narrate the Changes panel and
|
|
79
|
+
the restart loop.
|
|
80
|
+
2. Open a **files** tab in the right panel and show the edit the model made.
|
|
81
|
+
3. `+` → **Pi** (or Claude): the agent starts in the app folder; ask it for a route; run `.acryl/bin/acryl look` in that terminal and show the
|
|
82
|
+
page's snapshot.
|
|
83
|
+
4. Settings > Models: show where the key lives and that it is not in the app folder.
|
|
84
|
+
5. Show the registry listing with an app already published.
|
|
92
85
|
|
|
93
86
|
## Resetting between sessions
|
|
94
87
|
|
|
95
|
-
Everything a person makes lives inside their app folder and `~/acryl-workshop`. To reset a machine
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
rm -rf ~/acryl-workshop/[a-z]*-app ~/acryl-workshop/registry
|
|
99
|
-
cp -R ~/acryl-workshop/prepared/* ~/acryl-workshop/ # if you keep a prepared/ folder
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
Nothing is installed globally except the agent and Bun; neither needs cleaning between sessions.
|
|
88
|
+
Everything a person makes lives inside their app folder and `~/acryl-workshop`. To reset a machine, delete the app folders and copy the prepared one
|
|
89
|
+
back; nothing is installed globally except the agent, `gh` and Node. An app's data lives in its `.acrylblends/` (gitignored); the model key lives in
|
|
90
|
+
that home's credentials store, so a fresh copy starts without it.
|
|
103
91
|
|
|
104
92
|
## What is still open
|
|
105
93
|
|
|
106
|
-
-
|
|
107
|
-
|
|
108
|
-
|
|
94
|
+
- The frame's chat tab takes the focus when it binds its session after a restart; the app's tab is one click away and the guide says so.
|
|
95
|
+
- The frame's address is stable across restarts: the launcher keeps the token in the app home (owner-only, atomic) and reuses it, so an open page
|
|
96
|
+
comes back by reloading its URL even if the browser lost its cookie. `npx acrylblends open` prints the address of the running frame;
|
|
97
|
+
`npx acrylblends open --new` rotates it (the old address stops working at once and the new one is printed). The frame-side banner that names the
|
|
98
|
+
command is still to come (after the 120 gate work).
|
|
99
|
+
- The one-click WebBoxes.ai deploy and the browser-only section stay TODO(M9) until that workspace is live.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-acrylblends",
|
|
3
|
-
"version": "1.0
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "Create an Acryl app: npm create acrylblends@latest",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
"scaffold"
|
|
37
37
|
],
|
|
38
38
|
"dependencies": {
|
|
39
|
-
"acrylblends": "^1.0
|
|
39
|
+
"acrylblends": "^1.2.0",
|
|
40
40
|
"@webboxes/app-persistence": "0.1.1"
|
|
41
41
|
},
|
|
42
42
|
"publishConfig": {
|