@acryldev/create-blends 0.0.0-stage → 1.7.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 (103) hide show
  1. package/README.md +104 -2
  2. package/bin/create-acrylblends.js +12 -0
  3. package/dist/index.d.ts +94 -0
  4. package/dist/index.js +1069 -0
  5. package/dist/index.js.map +1 -0
  6. package/docs/framework/LICENSE +23 -0
  7. package/docs/framework/README.md +70 -0
  8. package/docs/framework/agents/index.md +59 -0
  9. package/docs/framework/api/acryl.md +247 -0
  10. package/docs/framework/api/context.md +478 -0
  11. package/docs/framework/api/exception.md +80 -0
  12. package/docs/framework/api/index.md +12 -0
  13. package/docs/framework/api/presets.md +62 -0
  14. package/docs/framework/api/request.md +396 -0
  15. package/docs/framework/api/routing.md +303 -0
  16. package/docs/framework/api/summary.md +143 -0
  17. package/docs/framework/concepts/benchmarks.md +26 -0
  18. package/docs/framework/concepts/developer-experience.md +5 -0
  19. package/docs/framework/concepts/middleware.md +21 -0
  20. package/docs/framework/concepts/motivation.md +14 -0
  21. package/docs/framework/concepts/routers.md +63 -0
  22. package/docs/framework/concepts/stacks.md +235 -0
  23. package/docs/framework/concepts/web-standard.md +27 -0
  24. package/docs/framework/cordis/acryl-in-a-cordis-app.md +160 -0
  25. package/docs/framework/cordis/concepts.md +105 -0
  26. package/docs/framework/cordis/middleware.md +8 -0
  27. package/docs/framework/cordis/migration-from-0-3.md +111 -0
  28. package/docs/framework/cordis/migration-from-0-4.md +14 -0
  29. package/docs/framework/cordis/migration-from-dsh-webserver.md +109 -0
  30. package/docs/framework/cordis/migration-to-1-0.md +46 -0
  31. package/docs/framework/cordis/mounting.md +85 -0
  32. package/docs/framework/cordis/node-server.md +100 -0
  33. package/docs/framework/cordis/plugin-lifecycle.md +111 -0
  34. package/docs/framework/cordis/surfaces.md +71 -0
  35. package/docs/framework/cordis/transport-and-cancellation.md +57 -0
  36. package/docs/framework/cordis/validation.md +135 -0
  37. package/docs/framework/getting-started/basic.md +201 -0
  38. package/docs/framework/getting-started/bun.md +219 -0
  39. package/docs/framework/getting-started/deploy.md +133 -0
  40. package/docs/framework/getting-started/desktop.md +80 -0
  41. package/docs/framework/getting-started/nodejs.md +365 -0
  42. package/docs/framework/getting-started/other-runtimes.md +30 -0
  43. package/docs/framework/guides/best-practices.md +231 -0
  44. package/docs/framework/guides/bring-your-own-tool.md +218 -0
  45. package/docs/framework/guides/client-modules.md +210 -0
  46. package/docs/framework/guides/create-acrylblends.md +143 -0
  47. package/docs/framework/guides/data.md +314 -0
  48. package/docs/framework/guides/examples.md +3 -0
  49. package/docs/framework/guides/faq.md +19 -0
  50. package/docs/framework/guides/forms-and-sessions.md +235 -0
  51. package/docs/framework/guides/helpers.md +33 -0
  52. package/docs/framework/guides/jsx-dom.md +301 -0
  53. package/docs/framework/guides/jsx.md +487 -0
  54. package/docs/framework/guides/middleware.md +253 -0
  55. package/docs/framework/guides/production.md +80 -0
  56. package/docs/framework/guides/rpc.md +878 -0
  57. package/docs/framework/guides/testing.md +133 -0
  58. package/docs/framework/guides/validation.md +470 -0
  59. package/docs/framework/helpers/accepts.md +60 -0
  60. package/docs/framework/helpers/adapter.md +57 -0
  61. package/docs/framework/helpers/conninfo.md +77 -0
  62. package/docs/framework/helpers/cookie.md +232 -0
  63. package/docs/framework/helpers/css.md +282 -0
  64. package/docs/framework/helpers/dev.md +64 -0
  65. package/docs/framework/helpers/factory.md +180 -0
  66. package/docs/framework/helpers/html.md +123 -0
  67. package/docs/framework/helpers/jwt.md +184 -0
  68. package/docs/framework/helpers/proxy.md +115 -0
  69. package/docs/framework/helpers/route.md +143 -0
  70. package/docs/framework/helpers/ssg.md +390 -0
  71. package/docs/framework/helpers/streaming.md +224 -0
  72. package/docs/framework/helpers/testing.md +118 -0
  73. package/docs/framework/helpers/websocket.md +208 -0
  74. package/docs/framework/middleware/builtin/basic-auth.md +165 -0
  75. package/docs/framework/middleware/builtin/bearer-auth.md +138 -0
  76. package/docs/framework/middleware/builtin/body-limit.md +71 -0
  77. package/docs/framework/middleware/builtin/cache.md +99 -0
  78. package/docs/framework/middleware/builtin/combine.md +94 -0
  79. package/docs/framework/middleware/builtin/compress.md +59 -0
  80. package/docs/framework/middleware/builtin/context-storage.md +74 -0
  81. package/docs/framework/middleware/builtin/cors.md +134 -0
  82. package/docs/framework/middleware/builtin/csrf.md +105 -0
  83. package/docs/framework/middleware/builtin/etag.md +54 -0
  84. package/docs/framework/middleware/builtin/ip-restriction.md +69 -0
  85. package/docs/framework/middleware/builtin/jsx-renderer.md +283 -0
  86. package/docs/framework/middleware/builtin/jwk.md +192 -0
  87. package/docs/framework/middleware/builtin/jwt.md +145 -0
  88. package/docs/framework/middleware/builtin/language.md +232 -0
  89. package/docs/framework/middleware/builtin/logger.md +74 -0
  90. package/docs/framework/middleware/builtin/loopback-only.md +31 -0
  91. package/docs/framework/middleware/builtin/method-not-allowed.md +48 -0
  92. package/docs/framework/middleware/builtin/method-override.md +80 -0
  93. package/docs/framework/middleware/builtin/mount.md +103 -0
  94. package/docs/framework/middleware/builtin/pretty-json.md +53 -0
  95. package/docs/framework/middleware/builtin/request-id.md +87 -0
  96. package/docs/framework/middleware/builtin/secure-headers.md +247 -0
  97. package/docs/framework/middleware/builtin/timeout.md +98 -0
  98. package/docs/framework/middleware/builtin/timing.md +100 -0
  99. package/docs/framework/middleware/builtin/trailing-slash.md +74 -0
  100. package/docs/framework/middleware/third-party.md +4 -0
  101. package/docs/framework/workshop/README.md +294 -0
  102. package/docs/framework/workshop/facilitator.md +101 -0
  103. package/package.json +54 -3
@@ -0,0 +1,219 @@
1
+ # Bun
2
+
3
+ > **Experimental.** Bun is not a verified runtime yet: the Acryl application code is the same, and the Bun adapter (`acrylblends/bun`) is checked on Bun in the framework's release check (a static file, the client address, a WebSocket echo), but the `bun` template and this guide are not covered by the release checks. Node.js is the verified runtime.
4
+
5
+
6
+ [Bun](https://bun.com) is another JavaScript runtime. It's not Node.js. Bun includes a transcompiler, so we can write the code in TypeScript or plain JavaScript.
7
+ Acryl also works on Bun.
8
+
9
+ ## 1. Install Bun
10
+
11
+ To install `bun` command, follow the instruction in [the official web site](https://bun.com).
12
+
13
+ ## 2. Setup
14
+
15
+ ### 2.1. Setup a new project
16
+
17
+ A starter for Bun is available. Start your project with "bun create" command.
18
+ Select `bun` template for this example.
19
+
20
+ ```sh
21
+ bun create acrylblends@latest my-app
22
+ ```
23
+
24
+ Move into my-app and install the dependencies.
25
+
26
+ ```sh
27
+ cd my-app
28
+ bun install
29
+ ```
30
+
31
+ ### 2.2. Setup an existing project
32
+
33
+ On an existing Bun project, we only need to install `acrylblends` dependencies on the project root directory via
34
+
35
+ ```sh
36
+ bun add acrylblends
37
+ ```
38
+
39
+ Then add the `dev` command to your existing `package.json`.
40
+
41
+ ```json
42
+ {
43
+ "scripts": {
44
+ "dev": "bun run --hot src/index.ts"
45
+ }
46
+ }
47
+ ```
48
+
49
+ See the Bun starter template for a minimal example setup. This is the output of running `bun create acrylblends@latest`.
50
+
51
+ ## 3. Hello World
52
+
53
+ "Hello World" script is below. Almost the same as writing on other platforms.
54
+
55
+ ```ts
56
+ import { Acryl } from '@acryldev/blends'
57
+
58
+ const app = new Acryl()
59
+ app.get('/', (c) => c.text('Hello Bun!'))
60
+
61
+ export default app
62
+ ```
63
+
64
+ If you are setting up Acryl on an existing project, the `bun run dev` command expects the "Hello World" script to be placed in `src/index.ts`
65
+
66
+ ## 4. Run
67
+
68
+ Run the command.
69
+
70
+ ```sh
71
+ bun run dev
72
+ ```
73
+
74
+ Then, access `http://localhost:3000` in your browser.
75
+
76
+ ## Change port number
77
+
78
+ You can specify the port number with exporting the `port`.
79
+
80
+ <!-- prettier-ignore -->
81
+ ```ts
82
+ import { Acryl } from '@acryldev/blends'
83
+
84
+ const app = new Acryl()
85
+ app.get('/', (c) => c.text('Hello Bun!'))
86
+
87
+ export default {
88
+ port: 3000,
89
+ fetch: app.fetch,
90
+ }
91
+ ```
92
+
93
+ ## Serve static files
94
+
95
+ To serve static files, use `serveStatic` from `acrylblends/bun`.
96
+
97
+ ```ts
98
+ import { serveStatic } from '@acryldev/blends/bun'
99
+
100
+ const app = new Acryl()
101
+
102
+ app.use('/static/*', serveStatic({ root: './' }))
103
+ app.use('/favicon.ico', serveStatic({ path: './favicon.ico' }))
104
+ app.get('/', (c) => c.text('You can access: /static/hello.txt'))
105
+ app.get('*', serveStatic({ path: './static/fallback.txt' }))
106
+ ```
107
+
108
+ For the above code, it will work well with the following directory structure.
109
+
110
+ ```
111
+ ./
112
+ ├── favicon.ico
113
+ ├── src
114
+ └── static
115
+ ├── demo
116
+ │ └── index.html
117
+ ├── fallback.txt
118
+ ├── hello.txt
119
+ └── images
120
+ └── dinotocat.png
121
+ ```
122
+
123
+ ### `rewriteRequestPath`
124
+
125
+ If you want to map `http://localhost:3000/static/*` to `./statics`, you can use the `rewriteRequestPath` option:
126
+
127
+ ```ts
128
+ app.get(
129
+ '/static/*',
130
+ serveStatic({
131
+ root: './',
132
+ rewriteRequestPath: (path) =>
133
+ path.replace(/^\/static/, '/statics'),
134
+ })
135
+ )
136
+ ```
137
+
138
+ ### `mimes`
139
+
140
+ You can add MIME types with `mimes`:
141
+
142
+ ```ts
143
+ app.get(
144
+ '/static/*',
145
+ serveStatic({
146
+ mimes: {
147
+ m3u8: 'application/vnd.apple.mpegurl',
148
+ ts: 'video/mp2t',
149
+ },
150
+ })
151
+ )
152
+ ```
153
+
154
+ ### `onFound`
155
+
156
+ You can specify handling when the requested file is found with `onFound`:
157
+
158
+ ```ts
159
+ app.get(
160
+ '/static/*',
161
+ serveStatic({
162
+ // ...
163
+ onFound: (_path, c) => {
164
+ c.header('Cache-Control', `public, immutable, max-age=31536000`)
165
+ },
166
+ })
167
+ )
168
+ ```
169
+
170
+ ### `onNotFound`
171
+
172
+ You can specify handling when the requested file is not found with `onNotFound`:
173
+
174
+ ```ts
175
+ app.get(
176
+ '/static/*',
177
+ serveStatic({
178
+ onNotFound: (path, c) => {
179
+ console.log(`${path} is not found, you access ${c.req.path}`)
180
+ },
181
+ })
182
+ )
183
+ ```
184
+
185
+ ### `precompressed`
186
+
187
+ The `precompressed` option checks if files with extensions like `.br` or `.gz` are available and serves them based on the `Accept-Encoding` header. It prioritizes Brotli, then Zstd, and Gzip. If none are available, it serves the original file.
188
+
189
+ ```ts
190
+ app.get(
191
+ '/static/*',
192
+ serveStatic({
193
+ precompressed: true,
194
+ })
195
+ )
196
+ ```
197
+
198
+ ## Testing
199
+
200
+ You can use `bun:test` for testing on Bun.
201
+
202
+ ```ts
203
+ import { describe, expect, it } from 'bun:test'
204
+ import app from '.'
205
+
206
+ describe('My first test', () => {
207
+ it('Should return 200 Response', async () => {
208
+ const req = new Request('http://localhost/')
209
+ const res = await app.fetch(req)
210
+ expect(res.status).toBe(200)
211
+ })
212
+ })
213
+ ```
214
+
215
+ Then, run the command.
216
+
217
+ ```sh
218
+ bun test index.test.ts
219
+ ```
@@ -0,0 +1,133 @@
1
+ # Deploy
2
+
3
+ This page runs an app made by `npm create @acryldev/blends@latest` (the `nodejs` and `notes` templates) on a Linux server with Node.js 22.19 or later: install, start, keep it running, put HTTPS in front, and look after the SQLite file.
4
+ The snippets are examples to adapt: check them against your own server before relying on them.
5
+
6
+ ## What the template already does
7
+
8
+ - **Port and address.** `src/index.ts` reads `PORT` (default 3000) and `HOST` (default `127.0.0.1`). The default is local on purpose, and `serve()` without a `hostname` binds `127.0.0.1` too (from acrylblends 0.7.2; earlier versions listened on every interface). In a container, set `HOST=0.0.0.0`.
9
+ - **Graceful stop.** On `SIGTERM` and `SIGINT` the server stops taking requests, closes idle connections, lets the requests in flight finish, closes the database (the `notes` template) and exits with 0. A connection that never ends cannot keep it alive past 10 seconds (it then exits with 1).
10
+ - **Errors.** An error answers `500 Internal Server Error` with no stack and no detail; the stack goes to the log (standard error).
11
+ - **Cookies.** The `notes` template marks its session cookie `Secure` when the request is HTTPS, or when `TRUST_PROXY=1` and the proxy sends `X-Forwarded-Proto: https`.
12
+
13
+ ## Environment variables
14
+
15
+ | Variable | Default | Meaning |
16
+ | --- | --- | --- |
17
+ | `NODE_ENV` | unset | set it to `production` on the server |
18
+ | `PORT` | `3000` | the port to listen on |
19
+ | `HOST` | `127.0.0.1` | the address to bind. `0.0.0.0` exposes the app to the network: do it in a container or when nothing else is in front |
20
+ | `NOTES_DB` | `data/notes.sqlite` in the working directory | the SQLite file (`notes` template); `CHAT_DB` is the `chat` template's (`data/chat.sqlite`). The folder is created, and the migrations in `migrations/` run at start. See [Data](../guides/data.md) |
21
+ | `TRUST_PROXY` | unset | `1` when a reverse proxy you run terminates HTTPS in front of the app (`notes` template) |
22
+ | `PUBLIC_ORIGIN` | unset | the address in the browser, for example `https://notes.example.com`. Behind a proxy the app sees `http://127.0.0.1:3000`, so csrf needs to be told which origin is the site (`notes` template) |
23
+
24
+ Keep secrets out of the repository: put them in an environment file the service reads (below), readable only by the service user.
25
+
26
+ ## Install and start
27
+
28
+ ```sh
29
+ git clone <your repository> /srv/notes && cd /srv/notes
30
+ npm ci --omit=dev
31
+ NODE_ENV=production PORT=3000 npm start
32
+ ```
33
+
34
+ `npm ci --omit=dev` installs `acrylblends` and `typescript`. `typescript` is a normal dependency on purpose (it is why a production install is bigger than the framework alone, about 20 MB more): `.tsx` pages are compiled when the app starts, by `acrylblends/node-server/register`, with the app's own `typescript`.
35
+ There is no build step today. When a build step appears (compiling client code, for instance) it belongs in `npm run build` before `npm start`, not in the start command.
36
+
37
+ ## Keep it running with systemd
38
+
39
+ `/etc/systemd/system/notes.service`:
40
+
41
+ ```ini
42
+ [Unit]
43
+ Description=Notes
44
+ After=network.target
45
+
46
+ [Service]
47
+ User=notes
48
+ WorkingDirectory=/srv/notes
49
+ EnvironmentFile=/etc/notes.env
50
+ ExecStart=/usr/bin/node --import acrylblends/node-server/register src/index.ts
51
+ Restart=on-failure
52
+ TimeoutStopSec=15
53
+ NoNewPrivileges=true
54
+ ProtectSystem=strict
55
+ ReadWritePaths=/var/lib/notes
56
+
57
+ [Install]
58
+ WantedBy=multi-user.target
59
+ ```
60
+
61
+ `/etc/notes.env` (mode `0640`, owned by root, group `notes`):
62
+
63
+ ```sh
64
+ NODE_ENV=production
65
+ PORT=3000
66
+ HOST=127.0.0.1
67
+ NOTES_DB=/var/lib/notes/notes.sqlite
68
+ TRUST_PROXY=1
69
+ PUBLIC_ORIGIN=https://notes.example.com
70
+ ```
71
+
72
+ ```sh
73
+ sudo useradd --system --home /srv/notes notes
74
+ sudo install -d -o notes -g notes /var/lib/notes
75
+ sudo systemctl daemon-reload && sudo systemctl enable --now notes
76
+ sudo systemctl stop notes # sends SIGTERM; the app exits within seconds
77
+ ```
78
+
79
+ `ExecStart` runs `node` directly (not `npm start`) so the signal reaches the app and not an `npm` wrapper.
80
+
81
+ ## Behind a reverse proxy
82
+
83
+ Let the proxy handle HTTPS and keep the app on `127.0.0.1`.
84
+
85
+ Caddy (`Caddyfile`), which also obtains the certificate:
86
+
87
+ ```text
88
+ notes.example.com {
89
+ reverse_proxy 127.0.0.1:3000
90
+ }
91
+ ```
92
+
93
+ nginx (certificates from your own tool, for example certbot):
94
+
95
+ ```nginx
96
+ server {
97
+ listen 443 ssl;
98
+ server_name notes.example.com;
99
+ # ssl_certificate and ssl_certificate_key here
100
+
101
+ location / {
102
+ proxy_pass http://127.0.0.1:3000;
103
+ proxy_set_header Host $host;
104
+ proxy_set_header X-Forwarded-Proto $scheme;
105
+ proxy_set_header X-Forwarded-For $remote_addr;
106
+ }
107
+ }
108
+ ```
109
+
110
+ Both pass `X-Forwarded-Proto`. Set `TRUST_PROXY=1` only when the app is reachable **only** through that proxy (it listens on `127.0.0.1`): the header is otherwise something any client can send.
111
+
112
+ ## The SQLite file and backups
113
+
114
+ The database is one file (plus `-wal` and `-shm` files while it is open). Keep it outside the code folder (`NOTES_DB=/var/lib/notes/notes.sqlite`), owned by the service user, on a disk you back up.
115
+ Do not copy the file while the app writes to it. Take a consistent copy with SQLite's backup, which is safe on a running database:
116
+
117
+ ```ts
118
+ import { DatabaseSync, backup } from 'node:sqlite'
119
+
120
+ const db = new DatabaseSync(process.env.NOTES_DB ?? 'data/notes.sqlite')
121
+ await backup(db, `/var/backups/notes-${new Date().toISOString().slice(0, 10)}.db`)
122
+ db.close()
123
+ ```
124
+
125
+ or, with the `sqlite3` command line tool installed: `sqlite3 /var/lib/notes/notes.sqlite ".backup '/var/backups/notes.db'"`. Run it from cron or a systemd timer and copy the result off the machine. To restore, stop the service and put the backup file in place of `notes.sqlite`.
126
+
127
+ ## Check it
128
+
129
+ ```sh
130
+ curl -I http://127.0.0.1:3000/ # the app, directly
131
+ curl -I https://notes.example.com/ # through the proxy
132
+ journalctl -u notes -n 50 # the log, including error stacks
133
+ ```
@@ -0,0 +1,80 @@
1
+ # Desktop
2
+
3
+ An Acryl app also runs as a desktop app: an Electron window opens on the app's own server. It is the same app and the same code as `npm run dev`; nothing in the app changes. A Blend app that runs inside the ACRYL frame
4
+ (it has `scripts/ide-host.mjs`) gets the whole frame in the window, the same one `npm run dev` serves to the browser: see [The frame in the window](#the-frame-in-the-window). This page covers a plain Acryl app (the `nodejs`
5
+ template) and a Blend app (the `agent` template or any other `acrylblends init` template). It runs from source today: packaging a distributable app (dmg, exe, deb) is not part of it yet.
6
+
7
+ ## Add it
8
+
9
+ In an app made by `npm create @acryldev/blends@latest my-app nodejs` (or `notes`, `chat`):
10
+
11
+ ```sh
12
+ cd my-app
13
+ npm install
14
+ npx acrylblends add desktop
15
+ npm install
16
+ npm run desktop
17
+ ```
18
+
19
+ In a Blend app, the same two commands (`npx acrylblends add desktop-shell`, `npm install`) add the Blend form of the shell, and `npx acrylblends init my-app --template todo --desktop` creates a Blend app with it already in.
20
+ `acrylblends add desktop-shell` chooses the right form: a Blend app (it depends on `@acryldev/instance`) or a plain Acryl app.
21
+
22
+ ## What it adds
23
+
24
+ - `plugins/desktop-web/` (a plain app) or the `@acryldev/desktop-shell` package (a Blend app, a dependency at the exact version of this release): the window code. Only it imports `electron`; the app's own code never does.
25
+ - `electron` as a development dependency (pinned to 44.9.3) and the script `npm run desktop`.
26
+ - `.acrylblends/` in `.gitignore`: Electron's user data (window state, cache, logs) lives in `.acrylblends/electron` inside the app's own folder, never in the user's application-data folder.
27
+
28
+ ## What `npm run desktop` does
29
+
30
+ 1. For a frame app, attaches to the running frame or starts its host (see [The frame in the window](#the-frame-in-the-window)). Otherwise it serves the app on `127.0.0.1` with a free port: for a plain app, `app.fetch` from `src/app.ts` (`export default app`) through `acrylblends/node-server`; for a Blend app, its own `createApp`.
31
+ 2. Takes a single-instance lock: a second launch of the same app focuses the first window and exits.
32
+ 3. Opens one window on the server's address, with a locked-down renderer (context isolation, no Node in the page, the sandbox, web security). Navigation stays on the app's own origin; a link to any other `http(s)` or `mailto` address opens in the system browser.
33
+ 4. When the window closes (or on SIGINT or SIGTERM), stops the server or frame host it started (never one it attached to) and exits.
34
+
35
+ ## The frame in the window
36
+
37
+ A Blend app made with the frame (`npm run dev` runs `scripts/ide-host.mjs`) opens the ACRYL frame in its desktop window, not only its page: the left panel with the
38
+ projects and sessions, the right panel with Files, Changes and Review, Settings, terminal tabs, the DSH chat, and the app's own page in a browser tile. It is the
39
+ same frame the browser shows; the desktop builds nothing of its own.
40
+
41
+ 1. When the frame already runs for this folder (`npm run dev` in another terminal), the window attaches to it: it reads the address the host keeps in
42
+ `.acrylblends/frame-url.json` (owner-only, with the launch token) and opens it. Closing the window leaves that host running.
43
+ 2. Otherwise the window starts the host itself, exactly as `npm run dev` does (the same npm and Node that ran `npm run desktop`; the host never runs inside
44
+ Electron), and opens the address it prints. Closing the window stops that host and everything it started, including its terminals, so its port is free
45
+ again. Ctrl-C in the terminal does the same: Electron runs in a process group of its own, and `npm run desktop` passes it exactly one signal (a second
46
+ one would end Electron before it could stop the host).
47
+ 3. Navigation follows ACRYL Desktop's rule: the frame's own address stays in the window, and its tiles (the app's page in an iframe) load freely. A link to any
48
+ other `http(s)` or `mailto` address opens in the system browser, and nothing else opens at all.
49
+ 4. The door's `window list` shows each window's address without the launch token.
50
+
51
+ The application menu's `Settings...` (`Cmd+,` on macOS, in the app menu; `Ctrl+,` and the File menu on Windows and Linux) opens the frame's own Settings, the dialog the left panel's Settings button opens. `acrylblends.desktopPath` does not apply to a frame app, because the frame opens the app's page in its tile on first run.
52
+
53
+ ## The first launch downloads Electron
54
+
55
+ `npm install` does not download Electron's binary (Electron 44 has no install script). The first `npm run desktop` does: about 100 MB, once per machine, then it is cached. Behind a proxy or mirror set `ELECTRON_MIRROR`
56
+ (and `ELECTRON_CACHE` to reuse a download); if the download is blocked, run `npx install-electron` where the mirror is reachable.
57
+
58
+ ## Linux: Ubuntu 23.10 and later
59
+
60
+ Ubuntu 23.10 and later restrict unprivileged user namespaces (`kernel.apparmor_restrict_unprivileged_userns=1`). Chromium's sandbox needs them, and an Electron unpacked by npm into `node_modules` has no AppArmor profile, so Electron stops at the start with "The SUID sandbox helper binary was found, but is not configured correctly" before the app runs.
61
+
62
+ `npm run desktop` starts through the shell's launcher (`acryl-desktop` in a Blend app, `plugins/desktop-web/launch.ts` in a plain one), which reads that sysctl. **Only when it is `1` on Linux** it starts Electron with `--no-sandbox` and prints one line saying so; on macOS, on Windows and on any Linux without the restriction Electron starts with its sandbox, as it always does. The window's renderer is still locked down (context isolation, no Node in the page, web security); what is lost is Chromium's process sandbox around it.
63
+
64
+ To keep the sandbox, give Electron an AppArmor profile that allows `userns`, as the VS Code and Chrome `.deb` packages do. Save this as `/etc/apparmor.d/my-app-electron` (the path is the one in your app's `node_modules`), then `sudo apparmor_parser -r /etc/apparmor.d/my-app-electron`:
65
+
66
+ ```text
67
+ abi <abi/4.0>,
68
+ include <tunables/global>
69
+
70
+ profile my-app-electron /path/to/my-app/node_modules/electron/dist/electron flags=(unconfined) {
71
+ userns,
72
+ include if exists <local/my-app-electron>
73
+ }
74
+ ```
75
+
76
+ The launcher then still sees the sysctl as `1` and passes `--no-sandbox`; set `ACRYLBLENDS_DESKTOP_SANDBOX=1` to start with the sandbox anyway.
77
+
78
+ ## A different start page
79
+
80
+ The window opens on `/`. To open another path, set it in `package.json`: `"acrylblends": { "desktopPath": "/todo" }`.