slicer-studio 0.2.1 → 0.3.1

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/README.md CHANGED
@@ -4,164 +4,252 @@ A 3D printing studio you add to any website with one HTML tag. Customers upload
4
4
  it costs to print. Staff can slice models and inspect the G-code.
5
5
 
6
6
  ```html
7
- <slicer-studio api-url="https://api.example.com"></slicer-studio>
7
+ <slicer-studio
8
+ api-url="https://api.example.com"
9
+ config='{"realtime":{"key":"your-public-key","host":"ws.example.com"}}'
10
+ ></slicer-studio>
8
11
  ```
9
12
 
10
13
  It is a standard custom element, so it works on any stack. It brings its own React, and a shadow root keeps its styles
11
14
  and your page's apart.
12
15
 
13
- The studio is the interface only. It needs a [slicer backend](#slicer-backend) that you run: headless OrcaSlicer behind a
14
- small web server, which does the slicing and holds your printers and prices.
16
+ The studio is the interface only. It needs a [slicer backend](#slicer-backend) that you run: an API in front of headless
17
+ OrcaSlicer, which does the slicing and holds your printers and prices.
15
18
 
16
19
  **The price page** (`mode="quote"`, the default) takes up to 10 models at once and shows each one in 3D. Customers choose
17
- the material, finish, strength and number of copies, then see the price, weight and print time. SLA and SLS jobs get an
18
- email button to your lab instead of a price.
20
+ the material, finish, strength and number of copies, then see the price, weight and print time. Every price uses your
21
+ default printer. SLA and SLS jobs get an email button to your lab instead of a price.
19
22
 
20
- **Advanced** (`mode="advanced"`) is for staff. It offers every printer and preset your backend lists, slices models, and
21
- shows the G-code layer by layer. It also opens G-code and sliced 3MF files in the browser, with no upload. You can
23
+ **Advanced** (`mode="advanced"`) is for staff. It offers your printers first, then every printer and preset your backend
24
+ lists, slices models, and shows the G-code layer by layer. Slicing needs your [staff routes](#staff-routes), which run on
25
+ your own login. It also opens G-code and sliced 3MF files in the browser, with no upload. You can
22
26
  [limit it to people your own servers approve](#staff-access).
23
27
 
24
- ## Contents
25
-
26
- - [How it works](#how-it-works)
27
- - [Slicer backend](#slicer-backend)
28
- - [Setup](#setup)
29
- - [Frameworks](#frameworks)
30
- - [Attributes](#attributes)
31
- - [Options](#options)
32
- - [Events and methods](#events-and-methods)
33
- - [Layout and styling](#layout-and-styling)
34
- - [Taking orders](#taking-orders)
35
- - [Staff access](#staff-access)
36
- - [Content Security Policy](#content-security-policy)
37
- - [Troubleshooting](#troubleshooting)
38
- - [Good to know](#good-to-know)
39
-
40
- ## How it works
41
-
42
- ```text
43
- Your website Your server
44
- +---------------------------+ +-----------------------------+
45
- | <slicer-studio> | model | Your slicer backend |
46
- | upload, choices, | ----------> | headless OrcaSlicer |
47
- | 3D view, price | <---------- | your printers and prices |
48
- +---------------------------+ weight, +-----------------------------+
49
- print time
50
- ```
51
-
52
- - **This package is the interface.** Your [slicer backend](#slicer-backend) does the slicing. Each backend has one set
53
- of printers and prices, so a lab runs one backend.
54
- - **Models go only to your backend.** The studio's only other calls are to your own servers, and only if you
55
- [limit Advanced](#staff-access). Those carry no models.
56
- - **Prices are worked out in the browser.** The backend returns weight and time, and the studio multiplies the weight
57
- by your price per gram. So you can change prices from your page, but you must not trust them when you charge
58
- (see [Taking orders](#taking-orders)).
59
- - **The package is already built.** You get ready-made JavaScript in `dist/`, and `npm install` adds no other packages.
60
28
 
61
29
  ## Slicer backend
62
30
 
63
- The backend is a headless OrcaSlicer setup. The studio does no slicing itself, so it can't price anything without a backend.
31
+ The backend is a headless OrcaSlicer setup behind a small API. The studio does no slicing itself, so it can't price
32
+ anything without a backend.
64
33
 
65
- The studio only talks to the five [routes](#routes) below, so the web server can be in any language.
66
- [Headless OrcaSlicer](#headless-orcaslicer) shows how to set up the slicing behind them.
34
+ A slice can take minutes, so no request stays open for it. The browser asks for a quote, sends the file straight to your
35
+ storage, then waits for a websocket event. That takes four parts:
36
+
37
+ | Part | What it does |
38
+ |---|---|
39
+ | API | Answers the [public routes](#public-routes), and the [staff routes](#staff-routes) if Advanced slices. Any language works |
40
+ | S3-compatible storage | Takes each upload through a signed form, and can hold the G-code |
41
+ | Pusher-compatible websocket server | Tells the page when a quote is done |
42
+ | Worker | Takes quotes from a queue and slices them, see [Headless OrcaSlicer](#headless-orcaslicer) |
67
43
 
68
44
  ### What each feature needs
69
45
 
70
46
  | To use | The backend needs |
71
47
  |---|---|
72
- | Price page with `estimate` | `/health`, `/api/config` and `/api/quote`, working out weight and time from the model's shape. Also `/api/options` if you set a `defaultPrinter` |
73
- | Price page with `exact` | The same, with a real slicer |
74
- | Advanced slicing | A real slicer, G-code from `/api/quote`, and `/api/options`. Also `/api/printers` to offer more than your own printers |
48
+ | Price page | The public routes, storage and a worker. Instant estimates from the model's shape are fine. Without the websocket each price can take up to a minute |
49
+ | Advanced slicing | The staff routes on your page's own origin, and a real slicer |
75
50
  | Opening G-code files in Advanced | Nothing. They stay in the browser |
76
51
 
77
- ### Routes
52
+ ### How a quote runs
53
+
54
+ 1. The studio sends `POST /quotes` with the file's details and settings, but not the file. Your API answers with an
55
+ `id`, a websocket `channel` and a signed upload form.
56
+ 2. It subscribes to the channel. This comes first because an estimate can finish about a second after the start, and the
57
+ event would be missed.
58
+ 3. It sends the file straight to your storage with the upload form.
59
+ 4. It sends `POST /quotes/{id}/start`, and your API queues the quote.
60
+ 5. Your worker slices the quote, then your backend publishes `quote.updated` on the channel.
61
+ 6. The studio reads the result once, with `GET /quotes/{id}`.
62
+
63
+ If no event comes, the studio checks once a minute, and once after the websocket reconnects. It gives up after 90
64
+ minutes, so every quote must reach `done` or `failed` before then.
65
+
66
+ ### Public routes
67
+
68
+ Give `api-url` the address these share. There is no login, because customers use them.
78
69
 
79
70
  | Route | Used for |
80
71
  |---|---|
81
- | [`GET /health`](#get-health) | Is the backend up, and can it slice? |
82
- | [`GET /api/config`](#get-apiconfig) | Your printers, prices and contact details |
83
- | [`POST /api/quote`](#post-apiquote) | A model's weight, time and size, and its G-code |
84
- | [`GET /api/options`](#get-apioptions) | What one printer offers |
85
- | [`GET /api/printers`](#get-apiprinters) | Every printer you can slice for |
72
+ | [`GET /config`](#get-config) | Your printers and prices |
73
+ | [`GET /options`](#get-options) | The materials for one printer |
74
+ | [`POST /quotes`](#post-quotes) | A new quote and its upload form |
75
+ | [`POST /quotes/{id}/start`](#post-quotesidstart) | Queue it once the file has arrived |
76
+ | [`GET /quotes/{id}`](#get-quotesid) | Its result |
86
77
 
87
78
  Every answer is JSON. If something fails, answer with an error status and a message, which the studio shows as it is:
88
79
 
89
80
  ```json
90
- { "error": "This model is too big for the printer's bed" }
81
+ { "message": "This model is too big for the printer's bed" }
91
82
  ```
92
83
 
93
- `401` is special: the studio then asks for a key, and sends it as an `x-api-key` header (see
94
- [Backend keys](#backend-keys)).
84
+ #### `GET /config`
95
85
 
96
- #### `GET /health`
86
+ ```json
87
+ {
88
+ "printers": ["Bambu Lab A1 0.4 nozzle", "Bambu Lab P1S 0.4 nozzle"],
89
+ "defaultPrinter": "Bambu Lab A1 0.4 nozzle",
90
+ "pricing": { "currency": "INR", "perGram": { "PLA": 6, "PETG": 7, "ABS": 8, "TPU": 7 }, "range": 20 },
91
+ "regularMode": { "supports": true, "mode": "estimate" }
92
+ }
93
+ ```
94
+
95
+ | Key | Meaning |
96
+ |---|---|
97
+ | `printers` | Your printers, listed first in Advanced |
98
+ | `defaultPrinter` | The printer every price uses. If it's blank, the first of `printers` |
99
+ | `pricing.range` | How far weight and time run above the figure on the page, in percent. `0` shows exact figures |
100
+ | `regularMode.supports` | Whether prices include supports, for the details popup |
101
+
102
+ The studio doesn't send `mode` or `supports` on these routes, so they are yours to decide. Your page can only override
103
+ `defaultPrinter`, see [Options](#options).
104
+
105
+ #### `GET /options`
106
+
107
+ The studio asks this with `?printer=Bambu%20Lab%20A1%200.4%20nozzle`.
97
108
 
98
109
  ```json
99
- { "ok": true, "slicer": true }
110
+ { "printer": "Bambu Lab A1 0.4 nozzle", "materials": ["ABS", "PETG", "PLA", "TPU"] }
100
111
  ```
101
112
 
102
- Set `slicer` to `false` if the backend can only estimate. Advanced then can't slice, and a price page on `exact` can't
103
- give a price.
113
+ List only the materials you price, because the studio offers no others. Answer `503` while the slicer is down, and the
114
+ price page says so before anyone uploads.
115
+
116
+ #### `POST /quotes`
104
117
 
105
- #### `GET /api/config`
118
+ The studio sends one request per file, as JSON:
106
119
 
107
120
  ```json
108
121
  {
109
- "printers": ["Bambu Lab A1 0.4 nozzle", "Bambu Lab P1S 0.4 nozzle"],
110
- "defaultPrinter": "Bambu Lab A1 0.4 nozzle",
111
- "pricing": { "currency": "INR", "perGram": { "PLA": 6, "PETG": 7, "ABS": 8, "TPU": 7 }, "range": 20 },
112
- "regularMode": { "supports": true, "mode": "estimate" },
113
- "contact": { "name": "Acme Labs", "email": "hello@example.com" }
122
+ "filename": "bracket.stl",
123
+ "size": 48210,
124
+ "printer": "Bambu Lab A1 0.4 nozzle",
125
+ "material": "PLA",
126
+ "quality": "standard",
127
+ "infill": 15,
128
+ "walls": 3
114
129
  }
115
130
  ```
116
131
 
117
- | Key | Meaning |
132
+ | Field | Value |
118
133
  |---|---|
119
- | `printers` | Your printers, listed first in Advanced. Use `[]` for none |
120
- | `defaultPrinter` | The printer every price uses. `null` lets the backend pick |
121
- | `pricing` | `currency`, `perGram` by material, and `range`, the percent the page adds on top. `null` shows no prices |
122
- | `regularMode` | `supports`: whether prices include supports. `mode`: `estimate`, `exact` or `auto`, which means `exact` when `/health` says it can slice |
123
- | `contact` | Your lab's `name`, and the `email` that SLA and SLS enquiries go to. Use `""` for neither |
134
+ | `filename` | Ends in `.stl`, `.3mf`, `.obj`, `.step`, `.stp`, `.iges` or `.igs`, in any case |
135
+ | `size` | The file's size in bytes, up to 52428800 (50 MB) |
136
+ | `printer` | Your default printer |
137
+ | `material` | One of the materials from `/options` |
138
+ | `quality` | `standard` (0.2 mm), `medium` (0.15 mm) or `high` (0.1 mm) |
139
+ | `infill` | `10`, `15`, `20`, `30`, `40`, `50`, `60`, `70`, `80` or `90` |
140
+ | `walls` | `1` to `6` |
124
141
 
125
- Your page can override everything here except `printers`, see [Options](#options).
142
+ Answer `201`:
126
143
 
127
- #### `POST /api/quote`
144
+ ```json
145
+ {
146
+ "id": "01m688sadqy04j83nhtswgrdtt",
147
+ "status": "awaiting_upload",
148
+ "channel": "quotes.01m688sadqy04j83nhtswgrdtt",
149
+ "upload": {
150
+ "url": "https://storage.example.com/slicer",
151
+ "fields": { "key": "uploads/01m688sadqy04j83nhtswgrdtt.stl", "Policy": "...", "X-Amz-Signature": "..." }
152
+ }
153
+ }
154
+ ```
128
155
 
129
- The studio sends one request per file, as `multipart/form-data`:
156
+ The studio sends `upload.fields` as they are to `upload.url`, in a multipart `POST`, with the file last as `file`. Any
157
+ `2xx` means it arrived. Sign the form for this one file, and limit its size in the policy.
130
158
 
131
- | Field | Value | Sent by |
132
- |---|---|---|
133
- | `model` | The file: `.stl`, `.3mf`, `.obj`, `.step`, `.stp`, `.iges` or `.igs`, up to 50 MB | Always |
134
- | `material` | Such as `PLA` | Always |
135
- | `printer` | A printer's name | Whenever one is chosen |
136
- | `quality` | `standard` (0.2 mm), `medium` (0.15 mm) or `high` (0.1 mm) | Price page. Advanced when set |
137
- | `infill` | A percentage: `10`, `15`, `20`, `30`, `40`, `50`, `60`, `70`, `80` or `90` | Price page. Advanced when set |
138
- | `walls` | `1` to `6` | Price page. Advanced when set |
139
- | `supports` | `true` or `false` | Price page. Advanced when set |
140
- | `rotX`, `rotY`, `rotZ` | `90`, `180` or `270`, the degrees to turn the model around each axis, in that order | When it's turned |
141
- | `mode` | `estimate` or `exact` | Price page |
142
- | `process`, `filament` | A preset's name, from `/api/options` | Advanced, when chosen |
143
- | `gcode` | `true`: send the G-code back | Advanced |
144
-
145
- Anything left out is yours to decide. Advanced leaves out `mode`, so slice for real.
159
+ **Limits:** answer `429` or `503` with `Retry-After` when you're busy. If that's 60 seconds or less, the studio shows
160
+ `Waiting for a free slot`, waits, and tries once more. So 10 files can pass a limit of 6 a minute. With a longer wait, or
161
+ no `Retry-After`, your message shows on that file.
162
+
163
+ #### `POST /quotes/{id}/start`
164
+
165
+ No body. Answer `202` and queue the quote. The studio treats `409` as already started, and shows any other error's
166
+ message, such as a file that hasn't arrived.
167
+
168
+ #### The `quote.updated` event
169
+
170
+ Publish this on the quote's public channel once, when it reaches `done` or `failed`. Its data doesn't matter, because the
171
+ studio only reads the result after it.
172
+
173
+ #### `GET /quotes/{id}`
146
174
 
147
175
  ```json
148
176
  {
149
- "stats": { "weightG": 12.33, "seconds": 1437, "sizeMm": [30, 30, 30], "estimated": true },
150
- "used": { "printer": "Bambu Lab A1 0.4 nozzle", "process": "0.20mm Standard", "filament": "Bambu PLA Basic" },
151
- "gcode": "; the whole file as text\nG1 X10 Y10 E1\n"
177
+ "id": "01m688sadqy04j83nhtswgrdtt",
178
+ "status": "done",
179
+ "error": null,
180
+ "stats": { "weightG": 4.63, "seconds": 662, "sizeMm": [20, 20, 20], "watertight": true, "estimated": true },
181
+ "used": { "printer": "Bambu Lab A1 0.4 nozzle", "process": "0.20mm Standard", "filament": "Generic PLA" },
182
+ "price": { "currency": "INR", "perGram": 6, "min": 28, "max": 33 }
152
183
  }
153
184
  ```
154
185
 
186
+ A failed quote has a message for the customer:
187
+
188
+ ```json
189
+ { "id": "01m688pmr3gg4465kyb4t8ska2", "status": "failed", "error": "This model could not be sliced", "stats": null, "used": null, "price": null }
190
+ ```
191
+
155
192
  | Key | Meaning |
156
193
  |---|---|
194
+ | `status` | `awaiting_upload`, `queued` or `processing` until it finishes as `done` or `failed` |
195
+ | `error` | Why it failed, shown on that file's card |
157
196
  | `stats.weightG` | Weight in grams, for one copy |
158
197
  | `stats.seconds` | Print time in seconds, for one copy |
159
198
  | `stats.sizeMm` | Width, depth and height in millimetres |
160
- | `stats.estimated` | `true` if this came from the model's shape, not a slicer. Leave it out otherwise |
161
- | `used` | Optional. What was really used, shown after slicing |
162
- | `gcode` | Only when asked for. Comment lines such as `;TYPE:Outer wall` and `;LAYER_CHANGE`, as OrcaSlicer writes them, let the view colour features and split layers |
199
+ | `stats.estimated` | `true` if this came from the model's shape, not a slicer. The page then says it's a quick estimate. Leave it out otherwise |
200
+ | `stats.watertight` | `false` warns that the model has holes |
201
+ | `used` | Optional. What was really used |
202
+ | `price` | `min` and `max` for one copy, in whole units of `currency`. The same number in both shows one price |
203
+
204
+ The page multiplies `price` by the copies. It works out no prices of its own, so your backend's rounding is what
205
+ customers see.
163
206
 
164
- #### `GET /api/options`
207
+ Answer `404` for a quote that has gone, and the studio asks the customer to try again.
208
+
209
+ ### Staff routes
210
+
211
+ These let Advanced slice. They are the quote routes above with more options, plus what only staff should have, and your
212
+ own login protects them. Name them with [`staffApi`](#options). Without it, Advanced only opens G-code files.
213
+
214
+ - **They must be on your page's own origin.** The studio relies on the page's cookies, so a page on another site can't use
215
+ them.
216
+ - **Every `POST` carries your CSRF token,** as `X-CSRF-TOKEN`, from `staffApi.csrfToken`.
217
+ - **Refusals explain themselves.** `401` shows `Sign in to slice`, `403` shows `Your account can't slice models`, and
218
+ `419` shows `Your session has expired. Reload the page`. Each stops the rest of the files.
219
+
220
+ | Route | Answer |
221
+ |---|---|
222
+ | [`GET /health`](#get-health) | Can it slice? |
223
+ | [`GET /printers`](#get-printers) | Every printer you can slice for |
224
+ | [`GET /options`](#staff-get-options) | What one printer offers, with presets |
225
+ | `POST /quotes` | As above, with [more fields](#staff-post-quotes) |
226
+ | `POST /quotes/{id}/start` | As above |
227
+ | `GET /quotes/{id}` | As above, with `hasGcode: true` once the G-code is ready. An optional `errorDetail` shows to staff in place of `error`, and `price` can be `null` for a material you don't price |
228
+ | `GET /quotes/{id}/gcode` | The G-code, or a redirect to a signed storage address |
229
+
230
+ G-code on another origin, such as a storage redirect, must allow your page's origin for `GET`. Comment lines such as
231
+ `;TYPE:Outer wall` and `;LAYER_CHANGE`, as OrcaSlicer writes them, let the view colour features and split layers.
232
+
233
+ #### `GET /health`
234
+
235
+ ```json
236
+ { "ok": true, "slicer": true }
237
+ ```
238
+
239
+ Set `slicer` to `false`, or answer `503`, if it can't slice right now. G-code files still open.
240
+
241
+ #### `GET /printers`
242
+
243
+ ```json
244
+ {
245
+ "printers": [{ "name": "Bambu Lab A1 0.4 nozzle", "vendor": "Bambu Lab", "model": "Bambu Lab A1", "nozzleMm": 0.4 }]
246
+ }
247
+ ```
248
+
249
+ Advanced groups these by brand, model and nozzle, after your `printers` from `/config`. If this fails, it offers only
250
+ those.
251
+
252
+ #### Staff `GET /options`
165
253
 
166
254
  The studio asks this with `?printer=Bambu%20Lab%20A1%200.4%20nozzle&material=PLA`.
167
255
 
@@ -175,19 +263,20 @@ The studio asks this with `?printer=Bambu%20Lab%20A1%200.4%20nozzle&material=PLA
175
263
  }
176
264
  ```
177
265
 
178
- `materials` is what the printer can use, and the studio offers no others. `filaments` lists the presets for the requested
179
- material.
266
+ `filaments` lists the presets for the requested material.
180
267
 
181
- #### `GET /api/printers`
268
+ #### Staff `POST /quotes`
182
269
 
183
- ```json
184
- {
185
- "printers": [{ "name": "Bambu Lab A1 0.4 nozzle", "vendor": "Bambu Lab", "model": "Bambu Lab A1", "nozzleMm": 0.4 }]
186
- }
187
- ```
270
+ The same JSON, where anything set to Default is left out, so the printer's own profile decides. `printer` can be any
271
+ printer. It always adds the first two of these:
188
272
 
189
- Advanced groups these by brand, model and nozzle. Answer with an error if you have no list, and it offers only your own
190
- printers and the backend's default.
273
+ | Field | Value |
274
+ |---|---|
275
+ | `mode` | `exact`: slice for real, because an estimate has no G-code |
276
+ | `gcode` | `true`: keep the G-code. A real boolean |
277
+ | `supports` | `true` or `false`, a real boolean. Left out, your own setting applies |
278
+ | `process`, `filament` | A preset's name, from `/options` |
279
+ | `rotX`, `rotY`, `rotZ` | `90`, `180` or `270`, the degrees to turn the model around each axis, in that order |
191
280
 
192
281
  ### Headless OrcaSlicer
193
282
 
@@ -199,9 +288,9 @@ parts:
199
288
  | OrcaSlicer | Slices the model. Use the Linux AppImage, unpacked so it doesn't need FUSE |
200
289
  | System libraries | What OrcaSlicer needs to start, such as GTK and OpenGL |
201
290
  | Xvfb | A virtual display, because OrcaSlicer needs one on Linux even from the command line |
202
- | Your web server | Answers the routes, runs OrcaSlicer for each request, and reads the result |
291
+ | Your worker | Takes a quote from the queue, runs OrcaSlicer on it, and reads the result |
203
292
 
204
- A container keeps these together. This installs everything except your web server, on x86-64. For arm64, use the file
293
+ A container keeps these together. This installs everything except your worker, on x86-64. For arm64, use the file
205
294
  with `aarch64` before the version in its name.
206
295
 
207
296
  ```dockerfile
@@ -219,7 +308,7 @@ RUN curl -fL https://github.com/OrcaSlicer/OrcaSlicer/releases/download/v2.4.2/O
219
308
  && rm /tmp/orca.AppImage
220
309
  ```
221
310
 
222
- **To slice a model,** start from a 3MF project saved in OrcaSlicer's desktop app. A 3MF is a zip, so for each request copy
311
+ **To slice a model,** start from a 3MF project saved in OrcaSlicer's desktop app. A 3MF is a zip, so for each quote copy
223
312
  that template, put the customer's mesh in it, and run this in a new folder. `HOME` must be a writable folder.
224
313
 
225
314
  ```bash
@@ -232,25 +321,11 @@ That writes `plate_1.gcode` to the output folder, with a `result.json` whose `er
232
321
  the 3MF, the mesh is in `3D/Objects/`, its position is in `3D/3dmodel.model` and `Metadata/model_settings.config`, and
233
322
  the printer and presets are in `Metadata/project_settings.config`.
234
323
 
235
- **Each part of an answer** comes from here:
236
-
237
- | The studio needs | Where it comes from |
238
- |---|---|
239
- | `slicer` in `/health` | Whether OrcaSlicer is installed |
240
- | `/api/printers`, `/api/options` | OrcaSlicer's own presets: JSON files in `/opt/orca/resources/profiles/<vendor>/`, under `machine`, `process` and `filament`. Follow each preset's `inherits` to get all its values |
241
- | `infill`, `quality`, `walls`, `supports` | The `--sparse-infill-density`, `--layer-height`, `--wall-loops` and `--enable-support` flags |
242
- | `printer`, `process`, `filament` | Those presets' values, merged into the project's `Metadata/project_settings.config` |
243
- | `weightG` | The G-code line `; filament used [g] = 4.00` |
244
- | `seconds` | The G-code line `; estimated printing time (normal mode) = 9m 54s`, or `model printing time:` on Bambu printers |
245
- | `gcode` | The text of `plate_1.gcode` |
246
- | `.3mf` and `.obj` uploads | `--export-stl --outputdir <folder> <file>` writes STL files to `<folder>/stl`, ready for the template |
247
- | `.step` and `.iges` uploads | A CAD reader such as `occt-import-js`, which turns them into a mesh |
248
- | `mode=estimate` | Not OrcaSlicer. Work weight and time out from the mesh's volume, which is instant |
249
324
 
250
325
  **To keep it reliable:**
251
326
 
252
- - **Slice one at a time.** OrcaSlicer is heavy, so queue requests and let them wait their turn.
253
- - **Stop a slice that runs too long.** Kill it after a limit, such as 3 minutes, and answer with an error.
327
+ - **Slice one at a time.** OrcaSlicer is heavy, so let quotes wait their turn in the queue.
328
+ - **Stop a slice that runs too long.** Kill it after a limit, such as 3 minutes, and fail the quote.
254
329
  - **Delete each job's folder** afterwards.
255
330
  - **Check the model fits first.** `printable_area` and `printable_height` in the `machine` preset give the printer's size.
256
331
  - **Expect a few bad presets.** Some vendor presets fail OrcaSlicer's own checks. Its log names the value, so you can
@@ -262,44 +337,44 @@ You need a server to run the backend. On your website you need either npm or a p
262
337
 
263
338
  ### 1. Run a slicer backend
264
339
 
265
- Set up [headless OrcaSlicer](#headless-orcaslicer) behind a web server that answers the [routes](#routes), then check that
340
+ Set up the [four parts](#slicer-backend), with [headless OrcaSlicer](#headless-orcaslicer) behind your API, then check that
266
341
  it answers:
267
342
 
268
343
  ```bash
269
- curl http://localhost:3000/health
344
+ curl https://api.example.com/config
270
345
  ```
271
346
 
272
- You should get `{"ok":true,"slicer":true}`.
347
+ You should get your printers and prices.
273
348
 
274
349
  ### 2. Set your printers and prices
275
350
 
276
- Make [`/api/config`](#get-apiconfig) answer with your own printers, prices and contact details. The studio reads this
277
- each time a page loads, so changes need no update to your site.
351
+ Make [`/config`](#get-config) answer with your own printers and prices. The studio reads this each time a page loads, so
352
+ changes need no update to your site.
278
353
 
279
354
  ### 3. Allow your website
280
355
 
281
- Browsers block calls to the backend from other sites until it allows them. Have every route answer with your site's
282
- exact origin, which is its scheme, host and port, with no path:
356
+ Browsers block calls to other sites until those sites allow them. Have your public routes answer with your site's exact
357
+ origin, which is its scheme, host and port, with no path. Answer `OPTIONS` requests too, because `POST /quotes` sends JSON:
283
358
 
284
359
  ```text
285
360
  Access-Control-Allow-Origin: https://www.example.com
361
+ Access-Control-Allow-Methods: GET, POST
362
+ Access-Control-Allow-Headers: content-type
363
+ Access-Control-Expose-Headers: Retry-After
286
364
  Vary: Origin
287
365
  ```
288
366
 
289
- Uploads need nothing more. If you use a [key](#backend-keys), also answer `OPTIONS` requests with these:
367
+ `Retry-After` must be exposed, or the studio can't see it and won't wait.
290
368
 
291
- ```text
292
- Access-Control-Allow-Methods: GET, POST
293
- Access-Control-Allow-Headers: x-api-key
294
- ```
369
+ Your storage needs CORS as well: `POST` from your site's origin, and `GET` if Advanced downloads G-code from it.
295
370
 
296
- You can skip this step by forwarding `/api/` and `/health` from your own domain. The studio then calls your site's own
297
- origin, so leave out `api-url`.
371
+ You can skip this for the routes by serving them from your own domain, with a path such as `api-url="/slicer"`. Storage
372
+ still needs it, because uploads go straight there.
298
373
 
299
374
  ### 4. Serve it over HTTPS
300
375
 
301
- A page on `https://` can't call an `http://` backend, so a live site needs HTTPS on the backend too. Put a proxy in front
302
- of it. With nginx:
376
+ A page on `https://` can't call `http://` or `ws://`, so a live site needs HTTPS on the API and storage, and `wss://` on
377
+ the websocket. Put a proxy in front of each. With nginx:
303
378
 
304
379
  ```nginx
305
380
  server {
@@ -307,26 +382,23 @@ server {
307
382
  server_name api.example.com;
308
383
  # ssl_certificate and ssl_certificate_key go here
309
384
 
310
- client_max_body_size 55m; # models can be up to 50 MB
311
-
312
385
  location / {
313
- proxy_pass http://127.0.0.1:3000; # your backend
386
+ proxy_pass http://127.0.0.1:3000; # your API
314
387
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
315
- proxy_read_timeout 300s; # a slice can wait for others in the queue
316
- proxy_send_timeout 300s;
317
388
  }
318
389
  }
319
390
  ```
320
391
 
321
392
  ### 5. Set its limits
322
393
 
323
- Slicing is heavy, and anyone can call a public backend, so set these however your server does:
394
+ Slicing is heavy, and anyone can call your public routes, so set these however your server does:
324
395
 
325
396
  | Limit | Why |
326
397
  |---|---|
327
- | Requests per visitor | Each file is one request and a customer can send 10 at once, so 30 a minute is a fair start |
328
- | 50 MB per upload | The studio won't send more than this, so everything in front of the backend must accept it |
329
- | At least 300 seconds per request | A slice can take minutes, more so when it waits for others |
398
+ | New quotes per visitor | Each file is one quote and a customer can send 10 at once. Above the limit, answer `429` with `Retry-After` |
399
+ | Quotes running per visitor | The studio runs one at a time, so a low limit is fine. Count abandoned uploads out after a while |
400
+ | Quotes running in total | A worker slices one at a time. Above the limit, answer `503` with `Retry-After` |
401
+ | 50 MB per upload | The studio won't send more. Enforce it in the upload form's policy |
330
402
 
331
403
  ### 6. Add the studio to your page
332
404
 
@@ -334,10 +406,15 @@ Slicing is heavy, and anyone can call a public backend, so set these however you
334
406
  npm install slicer-studio
335
407
  ```
336
408
 
337
- Import it once, anywhere in your JavaScript, then put the tag on your page:
409
+ Import it once, anywhere in your JavaScript, then put the tag on your page and name your websocket. Its key is public, so
410
+ it's safe in your page's source.
338
411
 
339
412
  ```js
340
413
  import 'slicer-studio';
414
+
415
+ document.querySelector('slicer-studio').config = {
416
+ realtime: { key: 'your-public-key', host: 'ws.example.com' },
417
+ };
341
418
  ```
342
419
 
343
420
  ```html
@@ -354,14 +431,16 @@ import 'slicer-studio';
354
431
 
355
432
  If it doesn't, see [Troubleshooting](#troubleshooting). Your browser's console usually names the problem.
356
433
 
357
- ### 8. Limit Advanced to staff
434
+ ### 8. Set up Advanced
358
435
 
359
- This step is optional. Until you do it, anyone who sets `mode="advanced"` can open Advanced. See
436
+ This step is optional. To slice in Advanced, add your [staff routes](#staff-routes) and name them in `staffApi`. Until you
437
+ limit it, anyone who sets `mode="advanced"` can open Advanced, but only your login lets them slice. See
360
438
  [Staff access](#staff-access).
361
439
 
362
440
  ## Frameworks
363
441
 
364
- Every example sets the same two options and logs the price. Replace `https://api.example.com` with your backend.
442
+ Every example names your websocket and logs the price. Replace `https://api.example.com` with your backend, and
443
+ `realtime` with your own.
365
444
 
366
445
  Tested on Vite 8, React 18.3 and 19.3, Next.js 16, Vue 3.5, Nuxt 4, Angular 20, Svelte 5 and Laravel 13.
367
446
 
@@ -370,13 +449,13 @@ Tested on Vite 8, React 18.3 and 19.3, Next.js 16, Vue 3.5, Nuxt 4, Angular 20,
370
449
  No npm or build step. Load it from a CDN:
371
450
 
372
451
  ```html
373
- <script type="module" src="https://cdn.jsdelivr.net/npm/slicer-studio@0.2.0/dist/slicer-studio.js"></script>
452
+ <script type="module" src="https://cdn.jsdelivr.net/npm/slicer-studio@0.3.0/dist/slicer-studio.js"></script>
374
453
 
375
454
  <slicer-studio api-url="https://api.example.com"></slicer-studio>
376
455
 
377
456
  <script>
378
457
  const studio = document.querySelector('slicer-studio');
379
- studio.config = { priceRange: 15, pricePerGram: { PLA: 5 } };
458
+ studio.config = { realtime: { key: 'your-public-key', host: 'ws.example.com' } };
380
459
  studio.addEventListener('estimate', e => console.log(e.detail));
381
460
  </script>
382
461
  ```
@@ -392,7 +471,7 @@ To host it yourself, copy the whole `node_modules/slicer-studio/dist` folder to
392
471
  import 'slicer-studio';
393
472
 
394
473
  const studio = document.querySelector('slicer-studio');
395
- studio.config = { priceRange: 15, pricePerGram: { PLA: 5 } };
474
+ studio.config = { realtime: { key: 'your-public-key', host: 'ws.example.com' } };
396
475
  studio.addEventListener('estimate', e => console.log(e.detail));
397
476
  ```
398
477
 
@@ -407,7 +486,7 @@ This works on React 18 and 19. Set `config` and listen for events in an effect:
407
486
  import { useEffect, useRef } from 'react';
408
487
  import 'slicer-studio';
409
488
 
410
- const options = { priceRange: 15, pricePerGram: { PLA: 5 } };
489
+ const options = { realtime: { key: 'your-public-key', host: 'ws.example.com' } };
411
490
 
412
491
  export default function PrintPrices() {
413
492
  const studio = useRef(null);
@@ -468,7 +547,7 @@ Then pass `config` as a property, with `.prop`:
468
547
  <script setup>
469
548
  import 'slicer-studio';
470
549
 
471
- const options = { priceRange: 15, pricePerGram: { PLA: 5 } };
550
+ const options = { realtime: { key: 'your-public-key', host: 'ws.example.com' } };
472
551
  const onEstimate = e => console.log(e.detail);
473
552
  </script>
474
553
 
@@ -499,7 +578,7 @@ Then keep the tag out of server rendering with `<ClientOnly>`:
499
578
 
500
579
  ```vue
501
580
  <script setup>
502
- const options = { priceRange: 15, pricePerGram: { PLA: 5 } };
581
+ const options = { realtime: { key: 'your-public-key', host: 'ws.example.com' } };
503
582
  const onEstimate = e => console.log(e.detail);
504
583
  </script>
505
584
 
@@ -526,7 +605,7 @@ import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
526
605
  `,
527
606
  })
528
607
  export class App {
529
- options = { priceRange: 15, pricePerGram: { PLA: 5 } };
608
+ options = { realtime: { key: 'your-public-key', host: 'ws.example.com' } };
530
609
 
531
610
  constructor() {
532
611
  import('slicer-studio');
@@ -552,7 +631,7 @@ This is for Svelte 5:
552
631
  <script>
553
632
  import 'slicer-studio';
554
633
 
555
- const options = { priceRange: 15, pricePerGram: { PLA: 5 } };
634
+ const options = { realtime: { key: 'your-public-key', host: 'ws.example.com' } };
556
635
  const onEstimate = e => console.log(e.detail);
557
636
  </script>
558
637
 
@@ -583,7 +662,7 @@ Pass the options from a route or controller:
583
662
 
584
663
  ```php
585
664
  Route::get('/prices', fn () => view('prices', [
586
- 'studio' => ['priceRange' => 15, 'pricePerGram' => ['PLA' => 5]],
665
+ 'studio' => ['realtime' => ['key' => 'your-public-key', 'host' => 'ws.example.com']],
587
666
  ]));
588
667
  ```
589
668
 
@@ -595,12 +674,23 @@ And in the Blade template:
595
674
  <slicer-studio api-url="{{ config('services.slicer.url') }}" config='@json($studio)'></slicer-studio>
596
675
  ```
597
676
 
677
+ If this app also serves your [staff routes](#staff-routes), add them for signed-in staff:
678
+
679
+ ```php
680
+ Route::get('/slicer', fn () => view('prices', [
681
+ 'studio' => [
682
+ 'realtime' => ['key' => 'your-public-key', 'host' => 'ws.example.com'],
683
+ 'staffApi' => ['url' => '/admin/slicer', 'csrfToken' => csrf_token()],
684
+ ],
685
+ ]))->middleware('auth');
686
+ ```
687
+
598
688
  ### Other server templates
599
689
 
600
690
  Write `config` as JSON in the attribute, inside single quotes, and escape any `'` in the values as `&#39;`:
601
691
 
602
692
  ```html
603
- <slicer-studio api-url="https://api.example.com" config='{"priceRange":15,"pricePerGram":{"PLA":5}}'></slicer-studio>
693
+ <slicer-studio api-url="https://api.example.com" config='{"realtime":{"key":"your-public-key","host":"ws.example.com"}}'></slicer-studio>
604
694
  ```
605
695
 
606
696
  ### TypeScript
@@ -643,7 +733,7 @@ const studio = useRef<SlicerStudioElement>(null);
643
733
 
644
734
  | Attribute | Values | Default |
645
735
  |---|---|---|
646
- | `api-url` | The address of your [slicer backend](#slicer-backend) | Your page's own origin |
736
+ | `api-url` | The address of your [public routes](#public-routes) | Your page's own origin |
647
737
  | `mode` | `quote` (the price page) or `advanced` (the staff tools) | `quote` |
648
738
  | `theme` | `light`, `dark` or `system`. Setting it hides the theme switch | Follows the device, and visitors can switch |
649
739
  | `config` | JSON of the [options](#options) | Nothing overridden |
@@ -652,17 +742,23 @@ You can change any of them at any time. Changing `api-url` or `mode` clears the
652
742
 
653
743
  ## Options
654
744
 
655
- Options override your backend's [`/api/config`](#get-apiconfig) for this page. Every key is optional. Set them as a
656
- property, which is easiest from JavaScript, or as JSON in the `config` attribute, which suits server templates.
745
+ Every key is optional, but without `realtime` each price can take up to a minute. Set them as a property, which is easiest
746
+ from JavaScript, or as JSON in the `config` attribute, which suits server templates.
747
+
748
+ Prices aren't an option. They come from your backend, so a page can't show one it doesn't hold.
657
749
 
658
750
  ```js
659
751
  document.querySelector('slicer-studio').config = {
660
- // these win over your backend's /api/config
661
- currency: 'INR',
662
- pricePerGram: { PLA: 5, PETG: 6 },
663
- priceRange: 15,
664
- regularMode: { supports: false, mode: 'estimate' },
752
+ // the websocket that says when a quote is done
753
+ realtime: { key: 'your-public-key', host: 'ws.example.com' },
754
+
755
+ // where Advanced slices, on your page's own origin
756
+ staffApi: { url: '/admin/slicer', csrfToken: 'your-pages-token' },
757
+
758
+ // your lab, for SLA and SLS enquiries
665
759
  contact: { name: 'Acme Labs', email: 'hello@example.com' },
760
+
761
+ // the printer for prices, in place of your backend's default
666
762
  defaultPrinter: 'Bambu Lab P1S 0.4 nozzle',
667
763
 
668
764
  // the choices a customer starts with
@@ -681,13 +777,15 @@ document.querySelector('slicer-studio').config = {
681
777
 
682
778
  | Key | Meaning |
683
779
  |---|---|
684
- | `currency` | A three-letter code such as `INR` or `USD` |
685
- | `pricePerGram` | Price per gram by material. Only the materials you list change |
686
- | `priceRange` | Shows cost, weight and time as a range, from the calculated figure up to this percent more. `0` shows exact figures |
687
- | `regularMode.supports` | `true` if estimates include supports |
688
- | `regularMode.mode` | `estimate` is instant, from the model's shape. `exact` is sliced for real, and takes seconds to minutes per file. `auto` uses `exact` when `/health` says the backend can slice |
780
+ | `realtime.key` | Your websocket server's public key. Required for `realtime` |
781
+ | `realtime.host` | Its host. Left out, Pusher's own servers for the `cluster` |
782
+ | `realtime.port` | Its port. `443` when left out |
783
+ | `realtime.cluster` | Its cluster. `mt1` when left out |
784
+ | `realtime.tls` | `false` for `ws://`, for local testing. `true` when left out |
785
+ | `staffApi.url` | The address of your [staff routes](#staff-routes), on your page's own origin |
786
+ | `staffApi.csrfToken` | The token for your page's session, sent on each `POST` |
689
787
  | `contact` | Your lab's `name`, and the `email` that SLA and SLS enquiries go to. The email button hides while no email is set |
690
- | `defaultPrinter` | The printer for estimates, which must be one your backend knows |
788
+ | `defaultPrinter` | The printer for prices, which must be one your backend allows |
691
789
  | `defaults.material` | `PLA`, `PETG`, `ABS` or `TPU`. If the printer doesn't offer it, the first one it does offer is used |
692
790
  | `defaults.quality` | `standard` (0.2 mm), `medium` (0.15 mm) or `high` (0.1 mm) |
693
791
  | `defaults.infill` | `10`, `15`, `20`, `30`, `40`, `50`, `60`, `70`, `80` or `90` |
@@ -696,12 +794,11 @@ document.querySelector('slicer-studio').config = {
696
794
  | `advanced` | The two servers that approve Advanced, see [Staff access](#staff-access) |
697
795
 
698
796
  - Setting `config` replaces the whole object, so include everything you want each time.
699
- - `pricePerGram`, `regularMode` and `contact` merge with your backend's values key by key.
700
797
  - `defaults` apply to files added after they are set.
701
798
  - Anything invalid is left out, with a `slicer-studio:` warning in the console. The exception is `advanced`: if it's
702
799
  there without both URLs, Advanced stays closed.
703
- - In `advanced` mode, only `defaultPrinter` and `advanced` have an effect, and `defaultPrinter` only until someone picks a
704
- printer. The studio then remembers their choice.
800
+ - In `advanced` mode, only `realtime`, `staffApi`, `defaultPrinter` and `advanced` have an effect, and `defaultPrinter`
801
+ only until someone picks a printer. The studio then remembers their choice.
705
802
 
706
803
  ### Cards
707
804
 
@@ -738,7 +835,7 @@ the copies. It doesn't fire for SLA or SLS, or in `advanced` mode. A typical `e.
738
835
  ```js
739
836
  {
740
837
  currency: 'INR',
741
- range: { low: 61, high: 71 }, // total cost; null if a material has no price
838
+ range: { low: 61, high: 71 }, // total cost; null if a file has no price
742
839
  gramsRange: { low: 12, high: 15 }, // total weight
743
840
  secondsRange: { low: 1380, high: 1680 }, // total print time, with prints run one after another
744
841
  unpriced: [], // materials with no price
@@ -746,6 +843,7 @@ the copies. It doesn't fire for SLA or SLS, or in `advanced` mode. A typical `e.
746
843
  files: [{
747
844
  name: 'bracket.stl',
748
845
  file: File, // the customer's File object
846
+ quoteId: '01m688sadqy04j83nhtswgrdtt', // to read the real price from your backend
749
847
  copies: 1,
750
848
  settings: { printer: '', material: 'PLA', quality: 'standard', infill: 15, walls: 3 },
751
849
  range: { low: 61, high: 71 }, // these three are for all of this file's copies
@@ -755,7 +853,8 @@ the copies. It doesn't fire for SLA or SLS, or in `advanced` mode. A typical `e.
755
853
  }
756
854
  ```
757
855
 
758
- With `priceRange` at `0`, `low` and `high` are the same exact figure. Otherwise they are whole numbers.
856
+ `range` is your backend's `price` times the copies. Weight and time are whole numbers, or the exact figure with
857
+ `pricing.range` at `0`.
759
858
 
760
859
  ### `modechange`
761
860
 
@@ -811,10 +910,11 @@ slicer-studio {
811
910
 
812
911
  ## Taking orders
813
912
 
814
- **Work the price out again on your server before you charge for it.** Everything in a browser can be changed, including
815
- the `estimate` event and your `pricePerGram`.
913
+ **Read the price from your backend before you charge for it.** Everything in a browser can be changed, including the
914
+ `estimate` event.
816
915
 
817
- The event includes each customer's `File`, so you can send the order to your server:
916
+ Each file in the event has a `quoteId`, so send those to your server. The event also has each customer's `File`, for the
917
+ model itself:
818
918
 
819
919
  ```js
820
920
  let order = null;
@@ -822,43 +922,39 @@ studio.addEventListener('estimate', e => { order = e.detail; });
822
922
 
823
923
  orderButton.addEventListener('click', async () => {
824
924
  const form = new FormData();
825
- for (const { file, copies, settings } of order.files) {
925
+ for (const { file, quoteId, copies } of order.files) {
826
926
  form.append('models', file);
827
- form.append('lines', JSON.stringify({ copies, settings }));
927
+ form.append('lines', JSON.stringify({ quoteId, copies }));
828
928
  }
829
929
  await fetch('/orders', { method: 'POST', body: form });
830
930
  });
831
931
  ```
832
932
 
833
- Then have your server ask your backend for each file's weight, with the same settings:
933
+ Then have your server read each quote:
834
934
 
835
935
  ```bash
836
- curl https://api.example.com/api/quote \
837
- -F model=@bracket.stl \
838
- -F "printer=Bambu Lab A1 0.4 nozzle" \
839
- -F material=PLA -F quality=standard -F infill=15 -F walls=3 \
840
- -F supports=true \
841
- -F mode=estimate
936
+ curl https://api.example.com/quotes/01m688sadqy04j83nhtswgrdtt
842
937
  ```
843
938
 
844
939
  ```json
845
- { "stats": { "weightG": 12.33, "seconds": 1437, "sizeMm": [30, 30, 30], "estimated": true } }
940
+ { "status": "done", "price": { "currency": "INR", "perGram": 6, "min": 28, "max": 33 } }
846
941
  ```
847
942
 
848
- - The studio's `settings` leave out the printer, supports and mode. Send your `defaultPrinter`, `regularMode.supports` and
849
- `regularMode.mode` for those.
850
- - The cost is `weightG × copies × price per gram`. The page shows that rounded down as `low`, and
851
- `cost × (1 + priceRange / 100)` rounded up as `high`.
943
+ - Check that `status` is `done`. Reject a quote that has gone, and send the customer back for a new price.
944
+ - `min` and `max` are for one copy, so multiply by `copies`.
945
+ - Read it when the order comes in, because your backend decides how long a quote lasts.
852
946
 
853
947
  ## Staff access
854
948
 
855
- Anyone can open Advanced until you set `advanced` in the [options](#options). With it set, the studio asks your own
856
- servers before it shows Advanced to a visitor.
949
+ Two options control Advanced, and they do different jobs:
950
+
951
+ - **`staffApi` says where it slices.** Your login protects those [routes](#staff-routes), so only your staff can slice,
952
+ whatever happens in the browser.
953
+ - **`advanced` says who can open it.** Anyone can open Advanced until you set it, though they can only open G-code files
954
+ without a login. With it set, the studio asks your own servers before it shows Advanced to a visitor.
857
955
 
858
- **This controls what the studio shows. It doesn't protect your backend.** A visitor can change the config in their
859
- browser's tools and open Advanced anyway. Anyone can also call a public backend directly, including with `gcode=true`,
860
- unless the backend itself refuses. If slicing must stay private, keep the backend private behind a
861
- [key](#backend-keys), with no public price page.
956
+ **`advanced` only controls what the studio shows.** A visitor can change the config in their browser's tools and open
957
+ Advanced anyway. It keeps the page tidy for customers, and your login on the staff routes keeps slicing private.
862
958
 
863
959
  ### How it works
864
960
 
@@ -892,7 +988,7 @@ Studio shows "Checking your access…" (Advanced isn't loaded yet)
892
988
  | The studio | No keys. It passes the token along, then forgets it |
893
989
  | Your slicer backend | Nothing. It never sees the token |
894
990
 
895
- Once Advanced is open, slicing goes to your backend as usual. Nothing checks again while it stays open, even after the
991
+ Once Advanced is open, slicing goes to your staff routes as usual. Nothing checks again while it stays open, even after the
896
992
  token expires. When someone leaves Advanced and comes back the whole check runs again, which is automatic if they're
897
993
  still signed in.
898
994
 
@@ -1020,24 +1116,13 @@ app.post('/slicer-verify', express.json(), (req, res) => {
1020
1116
 
1021
1117
  `verifyUrl` on another origin only needs your page's origin and the `content-type` header.
1022
1118
 
1023
- ### Backend keys
1024
-
1025
- A backend can require a key, which is a separate choice from the check above.
1026
-
1027
- - **Don't require one on a backend that serves a public price page.** The studio could load but not price anything, and
1028
- a key in a page's source isn't secret. That is why there is no attribute for one.
1029
- - **It does suit a staff-only backend.** Advanced has a key button, keeps the key in that browser, and sends it as
1030
- `x-api-key` to `/api/printers`, `/api/options` and `/api/quote`. Keep `/health` and `/api/config` open, because the
1031
- studio sends no key to them.
1032
- - **CORS limits browsers, not scripts,** so a public backend still needs a limit per visitor.
1033
-
1034
1119
  ## Content Security Policy
1035
1120
 
1036
1121
  If your site sends a CSP header, it needs these:
1037
1122
 
1038
1123
  ```text
1039
1124
  script-src 'self';
1040
- connect-src https://api.example.com;
1125
+ connect-src https://api.example.com https://storage.example.com wss://ws.example.com;
1041
1126
  img-src 'self' data: blob:;
1042
1127
  font-src data:;
1043
1128
  worker-src blob:;
@@ -1046,7 +1131,7 @@ worker-src blob:;
1046
1131
  | Directive | Why |
1047
1132
  |---|---|
1048
1133
  | `script-src` | Add `https://cdn.jsdelivr.net` if you load the package from the CDN |
1049
- | `connect-src` | Your backend, and `authUrl` and `verifyUrl` if you set them. Use `'self'` for anything on your own origin |
1134
+ | `connect-src` | Your API, your storage and your websocket, plus `authUrl` and `verifyUrl` if you set them. Use `'self'` for anything on your own origin |
1050
1135
  | `img-src` | Model pictures on the file cards |
1051
1136
  | `font-src` | The fonts are built in as data URIs. Without this the studio uses system fonts |
1052
1137
  | `worker-src` | Advanced's G-code reader. Without this it shows `Could not read this G-code: parser failed` |
@@ -1060,17 +1145,22 @@ from the toast library. They are harmless, because the studio's styles don't dep
1060
1145
  |---|---|---|
1061
1146
  | Nothing on the page, and the tag has no size | The package didn't load | Run `customElements.get('slicer-studio')` in the console. If it's `undefined`, check your import or script tag |
1062
1147
  | `The server can't be reached.` and `blocked by CORS policy` in the console | Your site isn't allowed | Have the backend send your exact origin, see [Allow your website](#3-allow-your-website) |
1063
- | `The server can't be reached.` and `ERR_CONNECTION_REFUSED` in the console | Wrong `api-url`, or the backend is down | Check `https://your-backend/health` in a browser |
1148
+ | `The server can't be reached.` and `ERR_CONNECTION_REFUSED` in the console | Wrong `api-url`, or the backend is down | Check `https://your-backend/config` in a browser |
1064
1149
  | `The server can't be reached.` and `Mixed Content` in the console | An `https://` page is calling an `http://` backend | [Serve it over HTTPS](#4-serve-it-over-https) |
1065
- | `Prices can't be worked out right now.` | The price page is on `exact`, and `/health` says `slicer: false` | Fix the slicer, or use `estimate` |
1066
- | `Slicing is off on this server.` in Advanced | `/health` says `slicer: false` | Fix the slicer. G-code files still open |
1067
- | `No price set for PLA yet` | That material has no price | Add it to `pricePerGram` |
1068
- | `This server needs an API key.` | The backend answered `401` | Remove the key from a public backend, see [Backend keys](#backend-keys) |
1150
+ | `Prices can't be worked out right now.` | `/options` answered `503` | Fix the slicer, then reload the page |
1151
+ | `The file could not be uploaded, please try again` | Storage refused the form, or blocked your origin | Check its CORS, see [Allow your website](#3-allow-your-website), and that the form hasn't expired |
1152
+ | A price takes a minute, and `live updates are off` in the console | The websocket didn't connect | Check `realtime`, your `connect-src`, and that the server is up |
1153
+ | `No price set for PLA yet` | `/options` listed a material with no price | List only the materials you price |
1154
+ | `Slicing isn't set up on this page` in Advanced | `staffApi` isn't set | Set it, see [Staff routes](#staff-routes). G-code files still open |
1155
+ | `Slicing is off on this server` in Advanced | `/health` says `slicer: false`, or answered `503` | Fix the slicer. G-code files still open |
1156
+ | `Sign in to slice` | A staff route answered `401` | Sign in on this site. The routes must be on the page's own origin |
1157
+ | `Your account can't slice models` | A staff route answered `403` | Give that account access |
1158
+ | `Your session has expired. Reload the page` | The CSRF token is out of date | Reload, and check that `staffApi.csrfToken` comes from the current session |
1159
+ | `The G-code could not be downloaded` | The G-code route or storage refused it | Check that storage allows `GET` from your page's origin |
1069
1160
  | `Advanced is for staff. Sign in and try again.` for someone who is signed in | `authUrl` got no cookie, or a server said no | Check both calls in the Network tab, and see [Keep `authUrl` safe](#keep-authurl-safe) |
1070
1161
  | `We couldn't check your access. Please try again.` | CORS, CSP, a wrong URL, or a server took over 8 seconds | The console names it. Check the CORS headers and `connect-src` |
1071
1162
  | `Advanced isn't set up on this page.` | `advanced` is missing a URL | Set both, see [Staff access](#staff-access) |
1072
- | Your backend's own message about too many requests | Your limit per visitor is too low | Raise it. Each file is one request |
1073
- | A large file fails, with status 413 in the browser's Network tab | Your proxy's upload limit is too low | Raise `client_max_body_size` in nginx |
1163
+ | Your backend's own message about too many requests | Your limit per visitor is too low | Raise it. Each file is one quote |
1074
1164
  | `slicer-studio: config is not valid JSON` | An object reached the `config` attribute as `[object Object]` | Set the `config` property in an effect, or use `JSON.stringify` |
1075
1165
  | `slicer-studio: unknown config key` | A typo in an option's name | Check it against [Options](#options) |
1076
1166
  | Your options and events do nothing, with no error | React 19's short form after server rendering | Use the [effect](#react) instead |
@@ -1084,7 +1174,8 @@ from the toast library. They are harmless, because the studio's styles don't dep
1084
1174
  - **Browsers:** Chrome and Edge 111+, Firefox 128+, Safari 16.4+. The 3D views need WebGL.
1085
1175
  - **Files:** STL, 3MF, OBJ, STEP and IGES, up to 10 at once and 50 MB each. STEP and IGES are priced but have no 3D
1086
1176
  preview. If your backend refuses a file, its message shows on that file's card.
1087
- - **Size:** about 210 kB gzipped to start, with the 3D view (about 250 kB) and the fonts (about 240 kB) loading after.
1177
+ - **Size:** about 215 kB gzipped to start, with the 3D view (about 250 kB) and the fonts (about 240 kB) loading after. The
1178
+ websocket client (about 18 kB) loads with the first quote.
1088
1179
  - **Server rendering:** importing the package on a server is safe, and does nothing. The studio has no server-rendered
1089
1180
  content, so set `config` and listeners in browser code, or give `config` as a JSON attribute.
1090
1181
  - **One studio per page:** a second one works, but both show every toast.
@@ -1092,7 +1183,7 @@ from the toast library. They are harmless, because the studio's styles don't dep
1092
1183
  - **What it adds to your page:** its fonts, some CSS `@property` rules, and one `<style>` for toasts. Nothing else touches
1093
1184
  your page.
1094
1185
  - **What it stores:** in `localStorage`, the visitor's theme (`print-preview.theme`) and, in Advanced, the last printer
1095
- (`print-preview.printer`) and the API key (`gcode-viewer.api-key`).
1186
+ (`print-preview.printer`).
1096
1187
  - **Updating:** run `npm update slicer-studio`, or change the version in your CDN link. Price and printer changes need no
1097
1188
  update, because the studio reads them from your backend.
1098
1189