slicer-studio 0.1.0 → 0.2.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
@@ -1,18 +1,341 @@
1
1
  # slicer-studio
2
2
 
3
- A 3D printing studio as one custom element. Put `<slicer-studio>` on a page, on any stack, and customers can upload
4
- their models and see what printing them costs, or staff can slice them and inspect the G-code. It brings its own React,
5
- and a shadow root keeps its styles and your page's apart.
3
+ A 3D printing studio you add to any website with one HTML tag. Customers upload a model, make a few choices and see what
4
+ it costs to print. Staff can slice models and inspect the G-code.
6
5
 
7
- It needs a running [slicer-api](https://github.com/kerala-startup-mission/slicer-api), which does the slicing and holds
8
- your printers and prices.
6
+ ```html
7
+ <slicer-studio api-url="https://api.example.com"></slicer-studio>
8
+ ```
9
+
10
+ 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
+ and your page's apart.
12
+
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.
15
+
16
+ **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.
19
+
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
22
+ [limit it to people your own servers approve](#staff-access).
23
+
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
+
61
+ ## Slicer backend
62
+
63
+ The backend is a headless OrcaSlicer setup. The studio does no slicing itself, so it can't price anything without a backend.
64
+
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.
67
+
68
+ ### What each feature needs
69
+
70
+ | To use | The backend needs |
71
+ |---|---|
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 |
75
+ | Opening G-code files in Advanced | Nothing. They stay in the browser |
76
+
77
+ ### Routes
78
+
79
+ | Route | Used for |
80
+ |---|---|
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 |
86
+
87
+ Every answer is JSON. If something fails, answer with an error status and a message, which the studio shows as it is:
88
+
89
+ ```json
90
+ { "error": "This model is too big for the printer's bed" }
91
+ ```
92
+
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)).
95
+
96
+ #### `GET /health`
97
+
98
+ ```json
99
+ { "ok": true, "slicer": true }
100
+ ```
101
+
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.
104
+
105
+ #### `GET /api/config`
106
+
107
+ ```json
108
+ {
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" }
114
+ }
115
+ ```
116
+
117
+ | Key | Meaning |
118
+ |---|---|
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 |
124
+
125
+ Your page can override everything here except `printers`, see [Options](#options).
126
+
127
+ #### `POST /api/quote`
128
+
129
+ The studio sends one request per file, as `multipart/form-data`:
130
+
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.
146
+
147
+ ```json
148
+ {
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"
152
+ }
153
+ ```
154
+
155
+ | Key | Meaning |
156
+ |---|---|
157
+ | `stats.weightG` | Weight in grams, for one copy |
158
+ | `stats.seconds` | Print time in seconds, for one copy |
159
+ | `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 |
163
+
164
+ #### `GET /api/options`
165
+
166
+ The studio asks this with `?printer=Bambu%20Lab%20A1%200.4%20nozzle&material=PLA`.
167
+
168
+ ```json
169
+ {
170
+ "printer": "Bambu Lab A1 0.4 nozzle",
171
+ "defaultProcess": "0.20mm Standard",
172
+ "materials": ["PLA", "PETG", "ABS", "TPU"],
173
+ "processes": ["0.20mm Standard", "0.16mm High Quality"],
174
+ "filaments": [{ "name": "Bambu PLA Basic", "material": "PLA" }]
175
+ }
176
+ ```
177
+
178
+ `materials` is what the printer can use, and the studio offers no others. `filaments` lists the presets for the requested
179
+ material.
180
+
181
+ #### `GET /api/printers`
182
+
183
+ ```json
184
+ {
185
+ "printers": [{ "name": "Bambu Lab A1 0.4 nozzle", "vendor": "Bambu Lab", "model": "Bambu Lab A1", "nozzleMm": 0.4 }]
186
+ }
187
+ ```
188
+
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.
191
+
192
+ ### Headless OrcaSlicer
193
+
194
+ OrcaSlicer is a desktop app, but it can also slice from the command line. On a server with no screen, the setup has four
195
+ parts:
196
+
197
+ | Part | What it does |
198
+ |---|---|
199
+ | OrcaSlicer | Slices the model. Use the Linux AppImage, unpacked so it doesn't need FUSE |
200
+ | System libraries | What OrcaSlicer needs to start, such as GTK and OpenGL |
201
+ | 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 |
203
+
204
+ A container keeps these together. This installs everything except your web server, on x86-64. For arm64, use the file
205
+ with `aarch64` before the version in its name.
206
+
207
+ ```dockerfile
208
+ FROM ubuntu:24.04
209
+
210
+ RUN apt-get update && apt-get install -y --no-install-recommends \
211
+ ca-certificates curl xvfb xauth \
212
+ libgtk-3-0t64 libwebkit2gtk-4.1-0 libgl1 libglu1-mesa libegl1 libosmesa6 \
213
+ libxkbcommon0 libdbus-1-3 libsecret-1-0 libnss3
214
+
215
+ RUN curl -fL https://github.com/OrcaSlicer/OrcaSlicer/releases/download/v2.4.2/OrcaSlicer_Linux_AppImage_Ubuntu2404_V2.4.2.AppImage -o /tmp/orca.AppImage \
216
+ && chmod +x /tmp/orca.AppImage \
217
+ && cd /tmp && ./orca.AppImage --appimage-extract >/dev/null \
218
+ && mv /tmp/squashfs-root /opt/orca \
219
+ && rm /tmp/orca.AppImage
220
+ ```
221
+
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
223
+ that template, put the customer's mesh in it, and run this in a new folder. `HOME` must be a writable folder.
224
+
225
+ ```bash
226
+ HOME=/tmp/orca-home xvfb-run -a /opt/orca/AppRun --slice 1 --outputdir /tmp/job --export-3mf out.gcode.3mf \
227
+ --sparse-infill-density=15% --layer-height=0.2 --wall-loops=3 --enable-support=1 \
228
+ /tmp/job/job.3mf
229
+ ```
230
+
231
+ That writes `plate_1.gcode` to the output folder, with a `result.json` whose `error_string` says why if it fails. Inside
232
+ the 3MF, the mesh is in `3D/Objects/`, its position is in `3D/3dmodel.model` and `Metadata/model_settings.config`, and
233
+ the printer and presets are in `Metadata/project_settings.config`.
234
+
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
+
250
+ **To keep it reliable:**
251
+
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.
254
+ - **Delete each job's folder** afterwards.
255
+ - **Check the model fits first.** `printable_area` and `printable_height` in the `machine` preset give the printer's size.
256
+ - **Expect a few bad presets.** Some vendor presets fail OrcaSlicer's own checks. Its log names the value, so you can
257
+ correct it and try again.
258
+
259
+ ## Setup
260
+
261
+ You need a server to run the backend. On your website you need either npm or a page whose HTML you can edit.
262
+
263
+ ### 1. Run a slicer backend
264
+
265
+ Set up [headless OrcaSlicer](#headless-orcaslicer) behind a web server that answers the [routes](#routes), then check that
266
+ it answers:
267
+
268
+ ```bash
269
+ curl http://localhost:3000/health
270
+ ```
271
+
272
+ You should get `{"ok":true,"slicer":true}`.
273
+
274
+ ### 2. Set your printers and prices
275
+
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.
278
+
279
+ ### 3. Allow your website
280
+
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:
283
+
284
+ ```text
285
+ Access-Control-Allow-Origin: https://www.example.com
286
+ Vary: Origin
287
+ ```
288
+
289
+ Uploads need nothing more. If you use a [key](#backend-keys), also answer `OPTIONS` requests with these:
9
290
 
10
- ## Quick start
291
+ ```text
292
+ Access-Control-Allow-Methods: GET, POST
293
+ Access-Control-Allow-Headers: x-api-key
294
+ ```
295
+
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`.
298
+
299
+ ### 4. Serve it over HTTPS
300
+
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:
303
+
304
+ ```nginx
305
+ server {
306
+ listen 443 ssl;
307
+ server_name api.example.com;
308
+ # ssl_certificate and ssl_certificate_key go here
309
+
310
+ client_max_body_size 55m; # models can be up to 50 MB
311
+
312
+ location / {
313
+ proxy_pass http://127.0.0.1:3000; # your backend
314
+ 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
+ }
318
+ }
319
+ ```
320
+
321
+ ### 5. Set its limits
322
+
323
+ Slicing is heavy, and anyone can call a public backend, so set these however your server does:
324
+
325
+ | Limit | Why |
326
+ |---|---|
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 |
330
+
331
+ ### 6. Add the studio to your page
11
332
 
12
333
  ```bash
13
334
  npm install slicer-studio
14
335
  ```
15
336
 
337
+ Import it once, anywhere in your JavaScript, then put the tag on your page:
338
+
16
339
  ```js
17
340
  import 'slicer-studio';
18
341
  ```
@@ -21,36 +344,322 @@ import 'slicer-studio';
21
344
  <slicer-studio api-url="https://api.example.com"></slicer-studio>
22
345
  ```
23
346
 
24
- Without a bundler, load it from a CDN:
347
+ [Frameworks](#frameworks) shows this for your stack, including how to use it without npm.
348
+
349
+ ### 7. Check that it works
350
+
351
+ 1. Open your page. The studio should appear.
352
+ 2. Drop an STL file on it.
353
+ 3. Click **Get the price**. A price should appear.
354
+
355
+ If it doesn't, see [Troubleshooting](#troubleshooting). Your browser's console usually names the problem.
356
+
357
+ ### 8. Limit Advanced to staff
358
+
359
+ This step is optional. Until you do it, anyone who sets `mode="advanced"` can open Advanced. See
360
+ [Staff access](#staff-access).
361
+
362
+ ## Frameworks
363
+
364
+ Every example sets the same two options and logs the price. Replace `https://api.example.com` with your backend.
365
+
366
+ 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
+
368
+ ### Plain HTML
369
+
370
+ No npm or build step. Load it from a CDN:
25
371
 
26
372
  ```html
27
- <script type="module" src="https://cdn.jsdelivr.net/npm/slicer-studio/dist/slicer-studio.js"></script>
373
+ <script type="module" src="https://cdn.jsdelivr.net/npm/slicer-studio@0.2.0/dist/slicer-studio.js"></script>
374
+
28
375
  <slicer-studio api-url="https://api.example.com"></slicer-studio>
376
+
377
+ <script>
378
+ const studio = document.querySelector('slicer-studio');
379
+ studio.config = { priceRange: 15, pricePerGram: { PLA: 5 } };
380
+ studio.addEventListener('estimate', e => console.log(e.detail));
381
+ </script>
382
+ ```
383
+
384
+ Keep the exact version in the link, so a new release can't change your page without you knowing.
385
+
386
+ To host it yourself, copy the whole `node_modules/slicer-studio/dist` folder to your site and point `src` at
387
+ `slicer-studio.js` inside it. It loads files from the `chunks` folder next to it, so one file on its own won't work.
388
+
389
+ ### Vite, webpack and other bundlers
390
+
391
+ ```js
392
+ import 'slicer-studio';
393
+
394
+ const studio = document.querySelector('slicer-studio');
395
+ studio.config = { priceRange: 15, pricePerGram: { PLA: 5 } };
396
+ studio.addEventListener('estimate', e => console.log(e.detail));
29
397
  ```
30
398
 
31
- Then allow your site on the API, under [Set up the API](#set-up-the-api).
399
+ Vite warns about chunk size when you build. That is expected, because the 3D view is large. It loads separately, after
400
+ the page.
401
+
402
+ ### React
403
+
404
+ This works on React 18 and 19. Set `config` and listen for events in an effect:
405
+
406
+ ```jsx
407
+ import { useEffect, useRef } from 'react';
408
+ import 'slicer-studio';
409
+
410
+ const options = { priceRange: 15, pricePerGram: { PLA: 5 } };
411
+
412
+ export default function PrintPrices() {
413
+ const studio = useRef(null);
414
+
415
+ useEffect(() => {
416
+ const el = studio.current;
417
+ const onEstimate = e => console.log(e.detail);
418
+
419
+ el.config = options;
420
+ el.addEventListener('estimate', onEstimate);
421
+ return () => el.removeEventListener('estimate', onEstimate);
422
+ }, []);
423
+
424
+ return <slicer-studio ref={studio} api-url="https://api.example.com" />;
425
+ }
426
+ ```
427
+
428
+ React 19 has a shorter form, for apps that render only in the browser. The event name is lowercase:
429
+
430
+ ```jsx
431
+ <slicer-studio api-url="https://api.example.com" config={options} onestimate={onEstimate} />
432
+ ```
433
+
434
+ ### Next.js
435
+
436
+ Use the [React](#react) component above, with `'use client'` as its first line, in the App Router:
437
+
438
+ ```jsx
439
+ 'use client';
440
+
441
+ import { useEffect, useRef } from 'react';
442
+ import 'slicer-studio';
443
+
444
+ // the rest is the same as the React example
445
+ ```
446
+
447
+ Then use it from a page as usual. The import does nothing on the server, so you don't need `next/dynamic`.
448
+
449
+ **Don't use React 19's shorter form here.** After server rendering, React doesn't set `config` or `onestimate` on the
450
+ element. Nothing warns you: the studio ignores your options and your handler never runs.
451
+
452
+ ### Vue
453
+
454
+ Tell Vue's compiler this is a custom element, in `vite.config.js`:
455
+
456
+ ```js
457
+ import vue from '@vitejs/plugin-vue';
458
+ import { defineConfig } from 'vite';
459
+
460
+ export default defineConfig({
461
+ plugins: [vue({ template: { compilerOptions: { isCustomElement: tag => tag === 'slicer-studio' } } })],
462
+ });
463
+ ```
464
+
465
+ Then pass `config` as a property, with `.prop`:
466
+
467
+ ```vue
468
+ <script setup>
469
+ import 'slicer-studio';
470
+
471
+ const options = { priceRange: 15, pricePerGram: { PLA: 5 } };
472
+ const onEstimate = e => console.log(e.detail);
473
+ </script>
474
+
475
+ <template>
476
+ <slicer-studio api-url="https://api.example.com" :config.prop="options" @estimate="onEstimate" />
477
+ </template>
478
+ ```
479
+
480
+ ### Nuxt
481
+
482
+ In `nuxt.config.ts`:
483
+
484
+ ```ts
485
+ export default defineNuxtConfig({
486
+ vue: { compilerOptions: { isCustomElement: tag => tag === 'slicer-studio' } },
487
+ });
488
+ ```
489
+
490
+ Load it in a browser-only plugin, `app/plugins/slicer-studio.client.ts` (on Nuxt 3, `plugins/slicer-studio.client.ts`):
491
+
492
+ ```ts
493
+ import 'slicer-studio';
494
+
495
+ export default defineNuxtPlugin(() => {});
496
+ ```
497
+
498
+ Then keep the tag out of server rendering with `<ClientOnly>`:
499
+
500
+ ```vue
501
+ <script setup>
502
+ const options = { priceRange: 15, pricePerGram: { PLA: 5 } };
503
+ const onEstimate = e => console.log(e.detail);
504
+ </script>
505
+
506
+ <template>
507
+ <ClientOnly>
508
+ <slicer-studio api-url="https://api.example.com" :config.prop="options" @estimate="onEstimate" />
509
+ </ClientOnly>
510
+ </template>
511
+ ```
512
+
513
+ ### Angular
514
+
515
+ Add `CUSTOM_ELEMENTS_SCHEMA`, and load the package with `import()`. A plain `import 'slicer-studio'` puts it in your first
516
+ bundle, which fails the default size limit with `bundle initial exceeded maximum budget`.
517
+
518
+ ```ts
519
+ import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
520
+
521
+ @Component({
522
+ selector: 'app-root',
523
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
524
+ template: `
525
+ <slicer-studio api-url="https://api.example.com" [config]="options" (estimate)="onEstimate($event)"></slicer-studio>
526
+ `,
527
+ })
528
+ export class App {
529
+ options = { priceRange: 15, pricePerGram: { PLA: 5 } };
530
+
531
+ constructor() {
532
+ import('slicer-studio');
533
+ }
534
+
535
+ onEstimate(e: Event) {
536
+ console.log((e as CustomEvent).detail);
537
+ }
538
+ }
539
+ ```
540
+
541
+ TypeScript also needs a declaration for that `import()`, in `src/slicer-studio.d.ts`:
542
+
543
+ ```ts
544
+ declare module 'slicer-studio';
545
+ ```
546
+
547
+ ### Svelte
548
+
549
+ This is for Svelte 5:
550
+
551
+ ```svelte
552
+ <script>
553
+ import 'slicer-studio';
554
+
555
+ const options = { priceRange: 15, pricePerGram: { PLA: 5 } };
556
+ const onEstimate = e => console.log(e.detail);
557
+ </script>
558
+
559
+ <slicer-studio api-url="https://api.example.com" config={options} onestimate={onEstimate}></slicer-studio>
560
+ ```
561
+
562
+ ### Laravel
563
+
564
+ Run `npm install slicer-studio`, then add this to `resources/js/app.js`:
565
+
566
+ ```js
567
+ import 'slicer-studio';
568
+
569
+ document.querySelector('slicer-studio')?.addEventListener('estimate', e => console.log(e.detail));
570
+ ```
571
+
572
+ Add the backend's address to `.env`, and read it in `config/services.php`:
573
+
574
+ ```dotenv
575
+ SLICER_API_URL=https://api.example.com
576
+ ```
577
+
578
+ ```php
579
+ 'slicer' => ['url' => env('SLICER_API_URL')],
580
+ ```
581
+
582
+ Pass the options from a route or controller:
583
+
584
+ ```php
585
+ Route::get('/prices', fn () => view('prices', [
586
+ 'studio' => ['priceRange' => 15, 'pricePerGram' => ['PLA' => 5]],
587
+ ]));
588
+ ```
589
+
590
+ And in the Blade template:
591
+
592
+ ```blade
593
+ @vite('resources/js/app.js')
594
+
595
+ <slicer-studio api-url="{{ config('services.slicer.url') }}" config='@json($studio)'></slicer-studio>
596
+ ```
597
+
598
+ ### Other server templates
599
+
600
+ Write `config` as JSON in the attribute, inside single quotes, and escape any `'` in the values as `&#39;`:
601
+
602
+ ```html
603
+ <slicer-studio api-url="https://api.example.com" config='{"priceRange":15,"pricePerGram":{"PLA":5}}'></slicer-studio>
604
+ ```
605
+
606
+ ### TypeScript
607
+
608
+ The package has no types of its own. `import 'slicer-studio'` works as it is, and Vue needs nothing more. For the tag in
609
+ React or Next.js, add this file, `slicer-studio.d.ts`, next to your component:
610
+
611
+ ```ts
612
+ import type { DetailedHTMLProps, HTMLAttributes } from 'react';
613
+
614
+ export interface SlicerStudioElement extends HTMLElement {
615
+ config: Record<string, unknown>;
616
+ getPrice(): Promise<void> | void;
617
+ }
618
+
619
+ declare module 'react' {
620
+ namespace JSX {
621
+ interface IntrinsicElements {
622
+ 'slicer-studio': DetailedHTMLProps<HTMLAttributes<SlicerStudioElement>, SlicerStudioElement> & {
623
+ 'api-url'?: string;
624
+ mode?: 'quote' | 'advanced';
625
+ theme?: 'light' | 'dark' | 'system';
626
+ config?: Record<string, unknown> | string;
627
+ onestimate?: (e: CustomEvent) => void;
628
+ };
629
+ }
630
+ }
631
+ }
632
+ ```
633
+
634
+ Then type your ref:
635
+
636
+ ```ts
637
+ import type { SlicerStudioElement } from './slicer-studio';
638
+
639
+ const studio = useRef<SlicerStudioElement>(null);
640
+ ```
32
641
 
33
642
  ## Attributes
34
643
 
35
644
  | Attribute | Values | Default |
36
645
  |---|---|---|
37
- | `api-url` | The slicer-api address | The page's own origin |
646
+ | `api-url` | The address of your [slicer backend](#slicer-backend) | Your page's own origin |
38
647
  | `mode` | `quote` (the price page) or `advanced` (the staff tools) | `quote` |
39
- | `theme` | `light`, `dark` or `system`. Setting it hides the theme switch | Follows the device, with a switch for the visitor |
40
- | `config` | JSON of the options below | Nothing overridden |
648
+ | `theme` | `light`, `dark` or `system`. Setting it hides the theme switch | Follows the device, and visitors can switch |
649
+ | `config` | JSON of the [options](#options) | Nothing overridden |
41
650
 
42
- The studio takes the width it is given, and lays itself out by that width, not the screen's. `quote` is as tall as its
43
- content. `advanced` fills `100dvh`; set your own `height` on the element to change that.
651
+ You can change any of them at any time. Changing `api-url` or `mode` clears the files in the studio.
44
652
 
45
653
  ## Options
46
654
 
47
- Set `config` as a property, or as a JSON attribute, which suits server templates. Every key is optional.
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.
48
657
 
49
658
  ```js
50
659
  document.querySelector('slicer-studio').config = {
51
- // the same names as printers.json, and they win over it
660
+ // these win over your backend's /api/config
52
661
  currency: 'INR',
53
- pricePerGram: { PLA: 5, PETG: 6 }, // only these materials change
662
+ pricePerGram: { PLA: 5, PETG: 6 },
54
663
  priceRange: 15,
55
664
  regularMode: { supports: false, mode: 'estimate' },
56
665
  contact: { name: 'Acme Labs', email: 'hello@example.com' },
@@ -61,36 +670,52 @@ document.querySelector('slicer-studio').config = {
61
670
 
62
671
  // the cards to show; all of them when left out
63
672
  cards: ['model', 'files', 'material', 'cost'],
673
+
674
+ // the servers that approve Advanced; anyone can open it when left out
675
+ advanced: {
676
+ authUrl: 'https://www.example.com/slicer-token',
677
+ verifyUrl: 'https://www.example.com/slicer-verify',
678
+ },
64
679
  };
65
680
  ```
66
681
 
67
682
  | Key | Meaning |
68
683
  |---|---|
69
- | `currency` | A code such as `INR` or `USD` |
70
- | `pricePerGram` | Price per gram by material, merged over the API's |
71
- | `priceRange` | Show costs, weights and times as a range: the calculated figure up to this percent more. `0` shows exact figures |
72
- | `regularMode.supports` | Whether estimates include supports |
73
- | `regularMode.mode` | `estimate` (instant, from the model's shape), `exact` (sliced by OrcaSlicer) or `auto` |
74
- | `contact` | The lab's `name`, and the `email` that SLA and SLS enquiries go to |
75
- | `defaultPrinter` | The printer for estimates, one the API has profiles for |
76
- | `defaults` | `material`, `quality` (`standard`, `medium`, `high`), `infill` (10, 15, 20, then every 10 to 90) and `walls` (1 to 6). They apply to files added after they are set |
77
- | `cards` | Which cards show. They keep their fixed order and the grid closes around the gaps |
78
-
79
- Costs are worked out in the browser, so `currency`, `pricePerGram` and `priceRange` need nothing from the API. Anything
80
- invalid is left out, with a warning in the console. `cards` and `defaults` apply to `quote` mode; the rest applies to both.
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 |
689
+ | `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 |
691
+ | `defaults.material` | `PLA`, `PETG`, `ABS` or `TPU`. If the printer doesn't offer it, the first one it does offer is used |
692
+ | `defaults.quality` | `standard` (0.2 mm), `medium` (0.15 mm) or `high` (0.1 mm) |
693
+ | `defaults.infill` | `10`, `15`, `20`, `30`, `40`, `50`, `60`, `70`, `80` or `90` |
694
+ | `defaults.walls` | `1` to `6` |
695
+ | `cards` | Which [cards](#cards) to show |
696
+ | `advanced` | The two servers that approve Advanced, see [Staff access](#staff-access) |
697
+
698
+ - 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
+ - `defaults` apply to files added after they are set.
701
+ - Anything invalid is left out, with a `slicer-studio:` warning in the console. The exception is `advanced`: if it's
702
+ 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.
81
705
 
82
706
  ### Cards
83
707
 
84
- The cards are `process`, `model`, `files`, `material` (material and finish), `strength`, `cost` and `contact` (shown for
85
- SLA and SLS). Hiding one also takes away what it does:
708
+ The price page is made of cards: `process`, `model`, `files`, `material` (material and finish), `strength`, `cost` and
709
+ `contact` (shown for SLA and SLS). They keep a fixed order, and the grid closes around any you hide. Hiding a card also
710
+ removes what it does:
86
711
 
87
712
  | Hidden | What happens |
88
713
  |---|---|
89
- | `process` | Always FDM. The theme switch sits on this card, so it goes too |
90
- | `material`, `strength` | Customers get the `defaults` values, which is how you fix a choice |
714
+ | `process` | Always FDM. The theme switch is on this card, so it goes too |
715
+ | `material`, `strength` | Customers get your `defaults`, which is how you fix a choice for them |
91
716
  | `files` | One file at a time: a new file replaces the current one |
92
- | `cost` | No Get the price button. Call `getPrice()` and show the `estimate` event yourself |
93
- | `model` and `files` | Nowhere to add a file, so `model` stays, with a console warning |
717
+ | `cost` | No **Get the price** button. Call `getPrice()` and show the `estimate` event yourself |
718
+ | `model` and `files` | There would be nowhere to add a file, so `model` stays, with a console warning |
94
719
 
95
720
  ## Events and methods
96
721
 
@@ -102,201 +727,375 @@ studio.addEventListener('estimate', e => {
102
727
  console.log(`${range.low} to ${range.high} ${currency} for ${files.length} files`);
103
728
  });
104
729
 
105
- studio.getPrice(); // what the Get the price button does
730
+ studio.getPrice(); // does what the Get the price button does
106
731
  ```
107
732
 
108
- `estimate` fires when every file is priced, and again when the totals change, such as when the customer changes the
109
- copies. `getPrice()` fires it again if everything is already priced. The event's `detail` holds:
733
+ ### `estimate`
110
734
 
111
- | Field | Meaning |
112
- |---|---|
113
- | `currency` | The currency code |
114
- | `range` | `{ low, high }` for all the files, or `null` while a material has no price |
115
- | `unpriced` | The materials with no price |
116
- | `gramsRange`, `secondsRange` | `{ low, high }` weight in grams and print time in seconds |
117
- | `quick` | `true` for estimates from the model's shape, not sliced |
118
- | `files` | One entry each: `name`, `file` (the customer's `File`), `copies`, `settings`, `range`, `gramsRange`, `secondsRange` |
735
+ Fires on the price page once every file is priced, and again whenever the totals change, such as when a customer changes
736
+ the copies. It doesn't fire for SLA or SLS, or in `advanced` mode. A typical `e.detail`:
119
737
 
120
- **Work the price out again on your server before you charge for it.** Anything in a browser can be changed, including
121
- this event.
738
+ ```js
739
+ {
740
+ currency: 'INR',
741
+ range: { low: 61, high: 71 }, // total cost; null if a material has no price
742
+ gramsRange: { low: 12, high: 15 }, // total weight
743
+ secondsRange: { low: 1380, high: 1680 }, // total print time, with prints run one after another
744
+ unpriced: [], // materials with no price
745
+ quick: true, // true if estimated from the model's shape, not sliced
746
+ files: [{
747
+ name: 'bracket.stl',
748
+ file: File, // the customer's File object
749
+ copies: 1,
750
+ settings: { printer: '', material: 'PLA', quality: 'standard', infill: 15, walls: 3 },
751
+ range: { low: 61, high: 71 }, // these three are for all of this file's copies
752
+ gramsRange: { low: 12, high: 15 },
753
+ secondsRange: { low: 1380, high: 1680 },
754
+ }],
755
+ }
756
+ ```
122
757
 
123
- `modechange` fires when the Simple / Advanced switch is used, with `{ mode }` in its `detail`.
758
+ With `priceRange` at `0`, `low` and `high` are the same exact figure. Otherwise they are whole numbers.
124
759
 
125
- ## Set up the API
760
+ ### `modechange`
126
761
 
127
- Set these on slicer-api. Its README explains each one.
762
+ Fires when someone uses the Simple / Advanced switch, or a refused visitor is sent back to the price page, with `{ mode }`
763
+ in `detail`. The switch only appears in `advanced` mode, and setting the attribute yourself doesn't fire the event.
128
764
 
129
- - `ALLOWED_ORIGINS`: the sites that embed the studio. Without it, browsers block calls from other sites.
130
- - `RATE_LIMIT_PER_MIN`: turn this on for any API a public page can reach.
131
- - `TRUST_PROXY`: how many proxies sit in front of the API.
132
- - Leave `API_KEY` unset behind a public price page. There is deliberately no attribute for a key: anything in a page's
133
- source is public.
765
+ ### `advanceddenied`
134
766
 
135
- Each deployment has one `printers.json`, so a lab runs its own API for its own printers and prices.
767
+ Fires when your servers don't approve a visitor for Advanced, just before the studio returns to the price page. Use it to
768
+ show your own sign-in. `e.detail.reason` is `refused`, `unreachable` or `not-set-up`, see
769
+ [When the check fails](#when-the-check-fails).
136
770
 
137
- ## On your stack
771
+ ### `getPrice()`
138
772
 
139
- **Laravel.** Import it in `resources/js/app.js`, then in a Blade template:
773
+ Prices every file that needs it, and `estimate` fires when it's done. If everything is already priced, `estimate` fires
774
+ again. It does nothing while there are no files, while SLA or SLS is selected, while a price is being worked out, or
775
+ when the backend can't be reached.
140
776
 
141
- ```blade
142
- <slicer-studio api-url="{{ config('services.slicer.url') }}" config='@json($studio)'></slicer-studio>
777
+ The element needs to be loaded first, so wait for it if your code might run earlier:
778
+
779
+ ```js
780
+ await customElements.whenDefined('slicer-studio');
781
+ studio.getPrice();
143
782
  ```
144
783
 
145
- **Vue.** Tell the compiler it's a custom element, in `vite.config.js`:
784
+ ## Layout and styling
785
+
786
+ The studio is as wide as its container, and you can style the tag like any block:
787
+
788
+ ```css
789
+ slicer-studio {
790
+ max-width: 1200px;
791
+ margin: 0 auto;
792
+ }
793
+ ```
794
+
795
+ - **Columns follow the studio's width, not the screen's.** It has one column below 640px, two up to 1023px and four from
796
+ 1024px, so a narrow sidebar gets the phone layout on a wide screen.
797
+ - **Height:** `quote` is as tall as its content. `advanced` fills `100dvh`, and your own `height` wins:
798
+
799
+ ```css
800
+ slicer-studio[mode="advanced"] { height: calc(100dvh - 64px); }
801
+ ```
802
+
803
+ - **Before it loads,** the tag has no size. To stop the page jumping, reserve some room:
804
+
805
+ ```css
806
+ slicer-studio:not(:defined) { display: block; min-height: 600px; }
807
+ ```
808
+
809
+ - **Your page's CSS can't reach inside.** There is no supported way to change the studio's colours or fonts yet, only
810
+ `theme`.
811
+
812
+ ## Taking orders
813
+
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`.
816
+
817
+ The event includes each customer's `File`, so you can send the order to your server:
146
818
 
147
819
  ```js
148
- vue({ template: { compilerOptions: { isCustomElement: tag => tag === 'slicer-studio' } } })
820
+ let order = null;
821
+ studio.addEventListener('estimate', e => { order = e.detail; });
822
+
823
+ orderButton.addEventListener('click', async () => {
824
+ const form = new FormData();
825
+ for (const { file, copies, settings } of order.files) {
826
+ form.append('models', file);
827
+ form.append('lines', JSON.stringify({ copies, settings }));
828
+ }
829
+ await fetch('/orders', { method: 'POST', body: form });
830
+ });
149
831
  ```
150
832
 
151
- ```vue
152
- <slicer-studio api-url="https://api.example.com" :config.prop="options" @estimate="onEstimate" />
833
+ Then have your server ask your backend for each file's weight, with the same settings:
834
+
835
+ ```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
153
842
  ```
154
843
 
155
- **React 19** passes properties and events straight through:
844
+ ```json
845
+ { "stats": { "weightG": 12.33, "seconds": 1437, "sizeMm": [30, 30, 30], "estimated": true } }
846
+ ```
156
847
 
157
- ```jsx
158
- <slicer-studio api-url="https://api.example.com" config={options} onestimate={onEstimate} />
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`.
852
+
853
+ ## Staff access
854
+
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.
857
+
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.
862
+
863
+ ### How it works
864
+
865
+ Your site decides who gets in. The studio only asks it and acts on the answer, and your slicer backend takes no part.
866
+
867
+ ```text
868
+ Staff member signs in to your site (your login, your cookie)
869
+ |
870
+ Your page sets mode="advanced"
871
+ |
872
+ Studio shows "Checking your access…" (Advanced isn't loaded yet)
873
+ |
874
+ 1. POST authUrl, with cookies, body {}
875
+ | Your server checks the login
876
+ | Staff: 200 { "token": "..." }, signed with your private key
877
+ | Not staff: 403
878
+ |
879
+ 2. POST verifyUrl, no cookies, body { "token": "..." }
880
+ | Your server checks the signature and expiry with your public key
881
+ | Valid: 200 { "valid": true }
882
+ | Not valid: 403
883
+ |
884
+ 3. Both passed: Advanced opens
885
+ Anything else: back to the price page
159
886
  ```
160
887
 
161
- **React 18 and older** only set attributes, so use JSON and a ref:
888
+ | Who | Holds |
889
+ |---|---|
890
+ | Your page | The two URLs |
891
+ | Your servers | Your login, the private key and the public key |
892
+ | The studio | No keys. It passes the token along, then forgets it |
893
+ | Your slicer backend | Nothing. It never sees the token |
162
894
 
163
- ```jsx
164
- const studio = useRef(null);
165
- useEffect(() => {
166
- const el = studio.current;
167
- el.addEventListener('estimate', onEstimate);
168
- return () => el.removeEventListener('estimate', onEstimate);
169
- }, []);
895
+ Once Advanced is open, slicing goes to your backend as usual. Nothing checks again while it stays open, even after the
896
+ token expires. When someone leaves Advanced and comes back the whole check runs again, which is automatic if they're
897
+ still signed in.
898
+
899
+ ### When the check fails
900
+
901
+ The visitor sees a toast and goes back to the price page, and [`advanceddenied`](#advanceddenied) fires with the reason.
902
+ To try again, set `mode="advanced"` again.
903
+
904
+ | Reason | What happened | Toast |
905
+ |---|---|---|
906
+ | `refused` | A server said no, or gave a bad answer | `Advanced is for staff. Sign in and try again.` |
907
+ | `unreachable` | A server was down or blocked, or took over 8 seconds | `We couldn’t check your access. Please try again.` |
908
+ | `not-set-up` | `advanced` is missing a URL | `Advanced isn’t set up on this page.` |
909
+
910
+ ### Set it up
911
+
912
+ Name your two servers, then set `mode`. They can be the same server, and either can be a path on your own site, such as
913
+ `/slicer-token`.
170
914
 
171
- <slicer-studio ref={studio} api-url="https://api.example.com" config={JSON.stringify(options)} />
915
+ ```js
916
+ studio.config = {
917
+ advanced: {
918
+ authUrl: 'https://www.example.com/slicer-token',
919
+ verifyUrl: 'https://www.example.com/slicer-verify',
920
+ },
921
+ };
922
+ studio.setAttribute('mode', 'advanced');
172
923
  ```
173
924
 
174
- Server rendering is safe: on a server the import does nothing, and the element starts in the browser.
925
+ Set `config` first, or use the JSON attribute. If `mode` comes first, Advanced can show for a moment before the check
926
+ starts.
175
927
 
176
- ## Good to know
928
+ Then add two routes. Any other answer refuses the visitor, and each call has 8 seconds.
177
929
 
178
- - **Size:** about 210 kB gzipped to start, with the 3D view (about 250 kB) and the fonts (about 240 kB) loading after.
179
- - **Content Security Policy:** Advanced's G-code reader needs `worker-src blob:`. Fonts load as data URIs, so `font-src`
180
- needs `data:`.
181
- - **Browsers:** recent Chrome, Edge and Firefox, and Safari 16.4 or newer.
182
- - **One studio per page:** a second works, but both show every toast.
183
- - **Popups** stay inside your page's stacking context, so a host element with a `transform`, or a higher `z-index`, can
184
- cover them.
185
- - **Theming:** colours can't be overridden yet.
186
-
187
- ## What's inside: the price page
188
-
189
- This is `mode="quote"`.
190
-
191
- A bento of tiles: the customer's model is the big one, the choices sit around it, and the price is the black tile.
192
- Phones get one column in reading order. Every estimate uses the lab's default printer, and supports and exact or
193
- quick estimates follow the config (`regularMode`), so the customer is never asked about them.
194
-
195
- - **How should we print it?** FDM (filament), SLA (resin) or SLS (nylon powder), for all the files.
196
- - **FDM** is priced here, with the tiles below.
197
- - **SLA and SLS** are quoted by the lab's team for now: their tile says what the process is good for and has an
198
- "Email us about SLA / SLS" button, a ready email to `contact.email` listing the customer's files (the button
199
- hides while no email is set).
200
- - **Model**: drop one model or several anywhere on the page, or choose them; up to 10, each up to 50 MB. The
201
- selected model stands on a plate, with its size and size lines around it. The toolbar centres the model, zooms, shows or hides the size lines and goes
202
- fullscreen; the axes in the corner turn with the view, and clicking a letter looks along that axis; **Reset view**
203
- goes back to the starting angle. STL, 3MF and OBJ are previewed; STEP and IGES can't be, but are priced all the
204
- same. No sliced layers here: those are for Advanced, whose model preview is the same viewer.
205
- - **Your files**: a box to add more files, and a card for each, two to a page, with a picture of the model, its size and how it
206
- stands. Once priced, a card shows the weight, print time and cost of all its copies, with a stepper for how many
207
- (1 to 50); copies only multiply the figures, so changing them needs no new estimate. The choice tiles show the
208
- selected file's settings; the ⋮ menu copies a file's settings (not its copies) to the other files, or
209
- removes it. Choices made before uploading are what the first files start with.
210
- - **Material** (PLA, PETG, ABS, TPU), **Finish** (a three-stop slider: Standard 0.2 mm, Fine 0.15 mm, Extra fine
211
- 0.1 mm) and **Strength** (infill 10% to 90%, walls 1 to 6), per file.
212
- - **Estimated price**: "Get the price" works out each file that needs it, one after another (its card says why if
213
- one fails; the others carry on). Cost, weight and time all show as ranges: the calculated figure rounded down, up to
214
- `priceRange` percent more rounded up, in whole rupees, grams and minutes (₹21.93 with 20% reads ₹21 – ₹27), the
215
- files' ranges added up, and the ⓘ says how the price is worked out. Print time assumes the prints run one after
216
- another. After a change a warning says so and it offers "Update the price"; once everything is priced, **View
217
- details** opens one line per file and the totals.
218
-
219
- Customers never see a way into Advanced from this mode. Each mode keeps its own files, so switching starts the other
220
- one fresh.
221
-
222
- ## What's inside: Advanced
223
-
224
- This is `mode="advanced"`, with every option, for whoever runs the printers:
225
-
226
- 1. **Models**: one or several, as on the price page, with **Turn** buttons (tip forward, tip sideways, spin) to set which side the selected one prints on. Steps 2 to 4 are the
227
- selected model's settings, so each model can have its own printer and presets; "Use for all" copies them to
228
- the other models. Each row shows the model's weight and time once sliced, with the total under the list.
229
- 2. **Printer**: "Our printers" (from `printers.json`) come first. "My printer" uses the house templates in
230
- slicer-api's `templates/`. Otherwise pick a brand, then a model,
231
- then the nozzle; all of OrcaSlicer's printers are listed. The last printer is remembered.
232
- 3. **Material**: the materials that printer has profiles for; process and filament presets are under
233
- "Process and filament presets".
234
- 4. **Print settings**: layer height, supports, and bars for infill and walls. "Default" sends nothing, so the printer's
235
- own profile decides; the reset button next to a bar goes back to it.
236
-
237
- "Slice model" (or "Slice 3 models") sends each model that needs it to `/api/quote` with `gcode=true`, one after
238
- another, and the view opens the selected model's G-code; select another row to see its own. G-code you already have opens
239
- with "Open G-code" (or drop it on the page), and so do sliced 3MF projects from Bambu Studio and OrcaSlicer
240
- (`.gcode.3mf`): with several plates it asks which one, and shows the plate's thumbnail under print details.
241
- These files are read in your browser, nothing is uploaded.
242
-
243
- In the view, lines are colored by feature with the share of filament each uses. Click a feature to hide it,
244
- Alt-click to see only it. The ruler on the right is the print's Z axis: drag its top and bottom handles to show
245
- only those layers. Switch between 3D, top and front views, show travel moves, drag to orbit, scroll to zoom,
246
- right-drag to pan. Weight, time and filament length are under the view; the info button has every detail.
247
-
248
- If the API has `API_KEY` set, enter it with the key icon; it is kept in that browser.
249
-
250
- ## Working on this repo
251
-
252
- Start slicer-api first (its `docker compose up --build -d` serves the API on port 3000).
930
+ | Route | The studio sends | Your answer to approve |
931
+ |---|---|---|
932
+ | `authUrl` | `POST` with cookies, body `{}` | `200` with `{ "token": "..." }` |
933
+ | `verifyUrl` | `POST` without cookies, body `{ "token": "..." }` | `200` with `{ "valid": true }` |
934
+
935
+ The token's format is up to you. The studio only passes it along, and doesn't keep it. A short signed JWT works well, so
936
+ make a key pair and keep both keys on your servers:
253
937
 
254
938
  ```bash
255
- npm install
256
- npm run dev
939
+ openssl ecparam -name prime256v1 -genkey -noout -out slicer-private.pem
257
940
  ```
258
941
 
259
- It opens at http://localhost:5173, with `/api` and `/health` forwarded to port 3000 (set `API_URL` for another address).
260
- `npm test` runs the tests. `npm run build` makes the package in `dist/`, and `npm run build:site` makes our own page in
261
- `dist-site/`.
942
+ ```bash
943
+ openssl ec -in slicer-private.pem -pubout -out slicer-public.pem
944
+ ```
262
945
 
263
- `src/element.js` is the element. It mounts `src/studio/Studio.jsx`, which picks the mode: the price page is
264
- `components/quote/QuotePage.jsx` (with a component per card next to it) and Advanced is `components/AdvancedPage.jsx`.
265
- What both share, the file list and slicing each file in turn, is `hooks/useModelFiles.js` on top of `lib/model-files.js`.
946
+ In these examples, replace the staff check with your own.
266
947
 
267
- `patches/` fixes Radix UI, which reads `document.activeElement` and so can't see focus move inside a shadow root.
268
- `npm install` applies the patches. When a Radix update comes, check that they still apply, and that arrow keys and Tab
269
- still work in menus and dialogs.
948
+ **Laravel,** with `firebase/php-jwt`, in `routes/web.php`:
270
949
 
271
- ### Our own page
950
+ ```php
951
+ use Firebase\JWT\JWT;
952
+ use Firebase\JWT\Key;
953
+ use Illuminate\Http\Request;
272
954
 
273
- `index.html` and `src/site.js` are the page we host: the element filling the window, with Advanced at `#advanced`.
955
+ Route::post('/slicer-token', function (Request $request) {
956
+ abort_unless($request->user()?->is_staff, 403);
274
957
 
275
- ```bash
276
- docker compose up --build -d
958
+ $token = JWT::encode(
959
+ ['sub' => (string) $request->user()->id, 'iat' => time(), 'exp' => time() + 900],
960
+ file_get_contents(storage_path('slicer-private.pem')),
961
+ 'ES256',
962
+ );
963
+
964
+ return response()->json(['token' => $token])->header('Cache-Control', 'no-store');
965
+ });
966
+
967
+ Route::post('/slicer-verify', function (Request $request) {
968
+ try {
969
+ JWT::decode((string) $request->input('token'), new Key(file_get_contents(storage_path('slicer-public.pem')), 'ES256'));
970
+ } catch (Throwable) {
971
+ return response()->json(['valid' => false], 403);
972
+ }
973
+
974
+ return response()->json(['valid' => true]);
975
+ });
277
976
  ```
278
977
 
279
- It is at http://localhost:8080. nginx forwards `/api` and `/health` to `API_UPSTREAM`, which defaults to the API on the
280
- same machine:
978
+ The studio can't send a CSRF token, so exempt both routes in `bootstrap/app.php`:
281
979
 
282
- ```bash
283
- API_UPSTREAM=http://api.example.com:3000 docker compose up --build -d
980
+ ```php
981
+ ->withMiddleware(function (Middleware $middleware) {
982
+ $middleware->validateCsrfTokens(except: ['slicer-token', 'slicer-verify']);
983
+ })
284
984
  ```
285
985
 
286
- Sites can also embed this page in an iframe. Each time its height changes, it tells the parent page, which can size the
287
- frame so it never scrolls inside:
986
+ **Node,** with `express` and `jsonwebtoken`:
288
987
 
289
- ```html
290
- <iframe id="sfl-quote" src="https://quote.example.org/" title="3D printing prices" allow="fullscreen" style="width: 100%; border: 0; height: 900px"></iframe>
291
- <script>
292
- addEventListener('message', e => {
293
- if (e.origin !== 'https://quote.example.org' || !e.data || e.data.type !== 'superfablab-quote:height') return;
294
- document.getElementById('sfl-quote').style.height = e.data.height + 'px';
295
- });
296
- </script>
988
+ ```js
989
+ import fs from 'node:fs';
990
+ import express from 'express';
991
+ import jwt from 'jsonwebtoken';
992
+
993
+ const privateKey = fs.readFileSync('slicer-private.pem');
994
+ const publicKey = fs.readFileSync('slicer-public.pem');
995
+
996
+ app.post('/slicer-token', requireStaff, (req, res) => {
997
+ const token = jwt.sign({ sub: String(req.user.id) }, privateKey, { algorithm: 'ES256', expiresIn: 900 });
998
+ res.set('Cache-Control', 'no-store').json({ token });
999
+ });
1000
+
1001
+ app.post('/slicer-verify', express.json(), (req, res) => {
1002
+ try {
1003
+ jwt.verify(req.body.token, publicKey, { algorithms: ['ES256'] });
1004
+ res.json({ valid: true });
1005
+ } catch {
1006
+ res.status(403).json({ valid: false });
1007
+ }
1008
+ });
297
1009
  ```
298
1010
 
299
- Replace `https://quote.example.org` with where this page is served. `allow="fullscreen"` lets the model preview go
300
- fullscreen; without it that button stays away.
1011
+ ### Keep `authUrl` safe
301
1012
 
302
- Built with React, react-three-fiber (three.js), Tailwind CSS, Radix UI, cmdk, Motion, TanStack Query, Lucide icons and Sonner.
1013
+ - **Only answer `POST`,** with `Cache-Control: no-store`.
1014
+ - **On another origin, allow your page's exact origin.** Send `Access-Control-Allow-Credentials: true`, and allow the
1015
+ `content-type` header. Never echo the request's `Origin` back, or any site could get a token for your signed-in staff.
1016
+ - **Use `SameSite=Lax` cookies,** and keep `authUrl` on the same site as the page. In a cross-site iframe the browser sends
1017
+ no cookies, so staff are refused.
1018
+ - **Keep tokens short.** 15 minutes is plenty. The studio checks each time someone enters Advanced, and doesn't close it
1019
+ when a token expires.
1020
+
1021
+ `verifyUrl` on another origin only needs your page's origin and the `content-type` header.
1022
+
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
+ ## Content Security Policy
1035
+
1036
+ If your site sends a CSP header, it needs these:
1037
+
1038
+ ```text
1039
+ script-src 'self';
1040
+ connect-src https://api.example.com;
1041
+ img-src 'self' data: blob:;
1042
+ font-src data:;
1043
+ worker-src blob:;
1044
+ ```
1045
+
1046
+ | Directive | Why |
1047
+ |---|---|
1048
+ | `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 |
1050
+ | `img-src` | Model pictures on the file cards |
1051
+ | `font-src` | The fonts are built in as data URIs. Without this the studio uses system fonts |
1052
+ | `worker-src` | Advanced's G-code reader. Without this it shows `Could not read this G-code: parser failed` |
1053
+
1054
+ `style-src` needs nothing added. Without `'unsafe-inline'`, the console logs two `Applying inline style violates` errors
1055
+ from the toast library. They are harmless, because the studio's styles don't depend on them.
1056
+
1057
+ ## Troubleshooting
1058
+
1059
+ | What you see | Cause | Fix |
1060
+ |---|---|---|
1061
+ | 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
+ | `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 |
1064
+ | `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) |
1069
+ | `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
+ | `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
+ | `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 |
1074
+ | `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
+ | `slicer-studio: unknown config key` | A typo in an option's name | Check it against [Options](#options) |
1076
+ | Your options and events do nothing, with no error | React 19's short form after server rendering | Use the [effect](#react) instead |
1077
+ | `Failed to resolve component: slicer-studio` | Vue doesn't know the tag | Set `isCustomElement`, see [Vue](#vue) |
1078
+ | `bundle initial exceeded maximum budget` | Angular's size limit | Load it with `import()`, see [Angular](#angular) |
1079
+ | `Could not find a declaration file for module 'slicer-studio'` | TypeScript and `import()` | Add `declare module 'slicer-studio';`, see [Angular](#angular) |
1080
+ | Popups appear in the wrong place or behind your header | A parent has a `transform`, or your header has a higher `z-index` | Remove the `transform`, or lower the header's `z-index` |
1081
+
1082
+ ## Good to know
1083
+
1084
+ - **Browsers:** Chrome and Edge 111+, Firefox 128+, Safari 16.4+. The 3D views need WebGL.
1085
+ - **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
+ 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.
1088
+ - **Server rendering:** importing the package on a server is safe, and does nothing. The studio has no server-rendered
1089
+ content, so set `config` and listeners in browser code, or give `config` as a JSON attribute.
1090
+ - **One studio per page:** a second one works, but both show every toast.
1091
+ - **Moving and removing:** moving the tag in the page keeps the customer's files. Removing it clears them.
1092
+ - **What it adds to your page:** its fonts, some CSS `@property` rules, and one `<style>` for toasts. Nothing else touches
1093
+ your page.
1094
+ - **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`).
1096
+ - **Updating:** run `npm update slicer-studio`, or change the version in your CDN link. Price and printer changes need no
1097
+ update, because the studio reads them from your backend.
1098
+
1099
+ ## License
1100
+
1101
+ ISC