@kupcad/playground 0.1.3 → 0.1.5

package/README.md

@@ -1,8 +1,8 @@
 # @kupcad/playground
 
 KupCAD in a page: a script's editor beside its model and its parameters, all run in the browser
-by the core compiled to WebAssembly, in a worker. One Svelte component, which the site (and later
-the PWA) embeds; it keeps nothing of the page's.
+by the core compiled to WebAssembly, in a worker. One Svelte component, which the site and the
+browser IDE embed; it keeps nothing of the page's.
 
 ```svelte
 <script>
@@ -18,7 +18,7 @@ the PWA) embeds; it keeps nothing of the page's.
   with itself), `wasm` (that worker's module, when not the one `@kupcad/wasm` ships),
   `viewerOptions`, `settings`, `shortcuts` (a page's own, listed before the viewer's in the
   pane's shortcuts dialog) and `shortcutsOpen` (bindable).
-* **For a host that shares or saves the script** (a PWA later; nothing of it here): `onsource`
+* **For a host that shares or saves the script** (the site's Share, the browser IDE): `onsource`
   is called with the script at each of the person's edits (not with the `source` it was given),
   and an `actions` snippet puts the host's own buttons in the model's toolbar, after Export
   (`.kc-control` gives them its look). It keeps no draft: a page loaded again shows `source`.
@@ -26,6 +26,15 @@ the PWA) embeds; it keeps nothing of the page's.
   component's, by `bind:this`) puts one in the editor in place of the person's, which the
   editor's undo takes back, and runs it at once on its own values, its model framed whole (an
   edit's keeps the camera); the core, the console and the layout stay as they are.
+* **For a host of several scripts** (the browser IDE's project): `open(script, restore)` opens
+  one as another document, the editor made again on it with an undo history of its own (none of
+  the last one's), run as `load` runs one; `snapshot()` is the editor as it is, its undo history
+  with it, for `open` to give back when the host opens that script again; `run()` runs the
+  script again as it is (what it imports changed), and `focus()` puts the focus in the editor
+  (a script the host just made). `files` is what the
+  script's imports read, by the paths the script names them by (`import { } from "./lib.kup"`
+  reads `lib.kup`), given with each run and export as the core's calls take them. `download`
+  (exported) saves bytes or a Blob as a file, as the exports are saved.
 * **When it runs** (`runner.js`, `Runner`): once the script stays as it is for a moment after an
   edit (`DELAY_MS`, 300), at once when a parameter's value changes or it starts. A run under
   way when the next starts is stopped (the worker drops or ends its call), so what is shown is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kupcad/playground",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "KupCAD in the browser: a script's editor, its model and its parameters, running on the core compiled to WebAssembly in a worker. One Svelte component a page embeds.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -24,10 +24,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@kupcad/editor": "0.1.3",
-    "@kupcad/protocol": "0.1.3",
-    "@kupcad/ui": "0.1.3",
-    "@kupcad/wasm": "0.1.3"
+    "@kupcad/editor": "0.1.5",
+    "@kupcad/protocol": "0.1.5",
+    "@kupcad/ui": "0.1.5",
+    "@kupcad/wasm": "0.1.5"
   },
   "devDependencies": {
     "@codemirror/lint": "^6.9.7",

package/src/Playground.svelte

@@ -10,8 +10,10 @@
   model's width); the sizes, what is hidden or folded, and how the view looks are kept in
   `settings` (the page's localStorage by default), and follow them as they are set. It keeps
   nothing else of the page's: the page gives the script it starts with (`source`) and another
-  in its place (`load`), and is told of each edit of it (`onsource`), for its own buttons in the
-  toolbar (`actions`) to share or save it.
+  in its place (`load`, or `open` for another document, with an undo history of its own), and
+  is told of each edit of it (`onsource`), for its own buttons in the toolbar (`actions`) to
+  share or save it. The files the script imports, a page of several scripts gives with them
+  (`files`).
 -->
 <script>
   import { onMount, untrack } from 'svelte';
@@ -42,7 +44,7 @@
   /** @import { ConsoleLine, Problem, Settings, ShortcutGroup } from '@kupcad/ui' */
   /** @import { Snippet } from 'svelte' */
   /** @import { ViewerOptions } from '@kupcad/ui/viewer/types' */
-  /** @import { KupcadApi, WorkerWasmSource } from '@kupcad/wasm/types' */
+  /** @import { KupcadApi, PreviewOptions, WorkerWasmSource } from '@kupcad/wasm/types' */
 
   /**
    * @typedef {object} Props
@@ -57,6 +59,9 @@
    *   by default the page's localStorage
    * @property {(source: string) => void} [onsource] the person's edit changed the script: it now
    *   is `source` (for a host to share it, or save it)
+   * @property {PreviewOptions['files']} [files] what the script's imports read, by the paths it
+   *   names them by (`import { } from "./lib.kup"` reads `lib.kup`), given with each run and
+   *   export
    * @property {Snippet} [actions] a host's own buttons in the model's toolbar, after Export
    *   (`.kc-control` gives them its look)
    * @property {readonly ShortcutGroup[]} [shortcuts] the host's own, listed before the viewer's
@@ -72,6 +77,7 @@
     viewerOptions = {},
     settings = localSettings(),
     onsource,
+    files,
     actions: hostActions,
     shortcuts = [],
     shortcutsOpen = $bindable(false),
@@ -109,6 +115,10 @@
    * view frames each one's model whole (another subject), where an edit's keeps the camera.
    */
   let loads = $state(0);
+  /** How many other documents the page opened: the editor is made again for each. */
+  let documents = $state(0);
+  /** The editor's snapshot the document opened last starts from, if it has one. */
+  let restored = $state.raw(/** @type {unknown} */ (undefined));
   let editor = $state(/** @type {EditorClass | null} */ (null));
   /** `check`'s findings of the script as it is, none while it changed since. */
   let findings = $state(/** @type {Finding[]} */ ([]));
@@ -147,7 +157,7 @@
       },
       onerror: (error) => (notice = errorText(error)),
     });
-    runner.run(value, {}, { now: true });
+    runner.run(value, {}, { now: true, files });
     return () => {
       runner?.dispose();
       made?.terminate();
@@ -165,7 +175,38 @@
     findings = [];
     overrides = {};
     loads += 1;
-    runner?.run(script, {}, { now: true });
+    runner?.run(script, {}, { now: true, files });
+  }
+
+  /**
+   * Opens `script` in the editor in place of the one there as another document: the editor made
+   * again on it, its undo history its own, not the last one's (`restore`, an earlier
+   * `snapshot()` of it, gives it back), and run at once as `load` runs one.
+   * @param {string} script one of the page's scripts
+   * @param {unknown} [restore] the snapshot the page kept when it opened another
+   */
+  export function open(script, restore) {
+    restored = restore;
+    documents += 1;
+    load(script);
+  }
+
+  /** The editor as it is now, its undo history with it, for `open` to give back: plain JSON. */
+  export function snapshot() {
+    return editor?.snapshot();
+  }
+
+  /**
+   * Runs the script again at once, as it is, on the panel's values: what it imports changed
+   * (`files`), which the page knows of and it doesn't.
+   */
+  export function run() {
+    runner?.run(value, plainValues(overrides), { now: true, files });
+  }
+
+  /** Puts the focus in the editor: a script the page made, to be written. */
+  export function focus() {
+    editor?.focus();
   }
 
   /** @param {string} line of the core's log, which goes to the console */
@@ -176,13 +217,13 @@
   /** @param {string} next the user's script */
   function edited(next) {
     findings = [];
-    runner?.run(next, plainValues(overrides));
+    runner?.run(next, plainValues(overrides), { files });
     onsource?.(next);
   }
 
   /** @param {ParamValues} values the panel's */
   function valuesChanged(values) {
-    runner?.run(value, values, { now: true });
+    runner?.run(value, values, { now: true, files });
   }
 
   /** @param {Problem | ConsoleLine} place a problem or a console line with a line, clicked */
@@ -194,7 +235,7 @@
   async function exportChosen(format) {
     if (!core) return;
     try {
-      const bytes = await core.build(value, { format, params: plainValues(overrides) });
+      const bytes = await core.build(value, { format, params: plainValues(overrides), files });
       download(bytes, `${name}.${format}`);
       notice = '';
     } catch (error) {
@@ -215,7 +256,16 @@
   style:--params-width="{paramsWidth}px"
 >
   <section class="code" aria-label="Script">
-    <Editor bind:value bind:editor findings={marks} label={name} onchange={edited} />
+    {#key documents}
+      <Editor
+        bind:value
+        bind:editor
+        findings={marks}
+        label={name}
+        restore={restored}
+        onchange={edited}
+      />
+    {/key}
     {#if notice}<p class="notice" role="alert">{notice}</p>{/if}
   </section>
   <Splitter

package/src/index.js

@@ -1,5 +1,7 @@
 // @kupcad/playground: KupCAD in a page, a script's editor, model and parameters on the core in a
-// worker (Playground.svelte), and when it runs the script (Runner), for a host of its own.
+// worker (Playground.svelte), when it runs the script (Runner), for a host of its own, and how
+// it gives the person a file (download).
 
 export { default as Playground } from './Playground.svelte';
+export { download } from './download.js';
 export { DELAY_MS, Runner } from './runner.js';

package/src/runner.js

@@ -2,10 +2,11 @@
 // edit, and at once when a parameter's value changes or the playground starts. A run under way
 // when the next starts is stopped (the core's worker drops or ends its call), so what comes is
 // the last script's. A run is the script's findings (`check`, quick: the editor marks them
-// first), then its preview (the model, its parameters, why it failed).
+// first), then its preview (the model, its parameters, why it failed), the files its imports
+// read given with it.
 
 /** @import { Finding, ParamValues, Preview } from '@kupcad/protocol/types' */
-/** @import { KupcadApi } from '@kupcad/wasm/types' */
+/** @import { KupcadApi, PreviewOptions } from '@kupcad/wasm/types' */
 
 /** How long the script stays as it is after an edit before it runs. */
 export const DELAY_MS = 300;
@@ -42,15 +43,15 @@ export class Runner {
 
   /**
    * Runs `source` with `values` once it stays so for the delay (a later call waits again), or at
-   * once.
+   * once; with `files`, what its imports read.
    * @param {string} source
    * @param {ParamValues} values
-   * @param {{ now?: boolean }} [when]
+   * @param {{ now?: boolean, files?: PreviewOptions['files'] }} [options]
    */
-  run(source, values, { now = false } = {}) {
+  run(source, values, { now = false, files } = {}) {
     clearTimeout(this.#waiting);
-    if (now) void this.#start(source, values);
-    else this.#waiting = setTimeout(() => void this.#start(source, values), this.#delayMs);
+    if (now) void this.#start(source, values, files);
+    else this.#waiting = setTimeout(() => void this.#start(source, values, files), this.#delayMs);
   }
 
   /** Runs nothing more, and stops the run under way. */
@@ -63,8 +64,9 @@ export class Runner {
   /**
    * @param {string} source
    * @param {ParamValues} values
+   * @param {PreviewOptions['files']} files
    */
-  async #start(source, values) {
+  async #start(source, values, files) {
     this.#running?.abort();
     const running = new AbortController();
     this.#running = running;
@@ -73,7 +75,7 @@ export class Runner {
       const findings = await this.#kupcad.check(source, { signal });
       if (signal.aborted) return;
       this.#handlers.onfindings(findings, source);
-      const preview = await this.#kupcad.preview(source, { params: values, signal });
+      const preview = await this.#kupcad.preview(source, { params: values, files, signal });
       if (signal.aborted) return;
       this.#handlers.onpreview(preview, source);
     } catch (error) {