@kupcad/playground 0.1.4 → 0.1.6

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,11 +26,22 @@ 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; `open(text, restore, 'json')` opens a JSON file of the project (a
+  package's `kupcad.json` or `kupcad.lock`, data a script imports) the same way, edited with nothing
+  run, no model, status or parameters shown. `snapshot()` is the editor as it is, its undo history
+  with it, for `open` to give back when the host opens that file 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
-  the last script's. A run is `check` first, whose findings the editor marks at once, then the
-  preview: the model, how the run went, its parameters.
+  edit (`DELAY_MS`, 300), at once when a parameter's value changes or it starts (with a script: one
+  that starts empty runs nothing, and says nothing of a run, until something is typed). A run under
+  way when the next starts is stopped (the worker drops or ends its call), so what is shown is the
+  last script's. A run is `check` first, whose findings the editor marks at once, then the preview:
+  the model, how the run went, its parameters.
 * **What the editor marks** (`marks.js`): `check`'s findings, and the places the run named (why
   it failed, a warning on a line); not the run's error where `check` found errors already (a
   script that doesn't parse fails the run for the same reason). Findings of a script changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kupcad/playground",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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,12 +24,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@kupcad/editor": "0.1.4",
-    "@kupcad/protocol": "0.1.4",
-    "@kupcad/ui": "0.1.4",
-    "@kupcad/wasm": "0.1.4"
+    "@kupcad/editor": "0.1.6",
+    "@kupcad/protocol": "0.1.6",
+    "@kupcad/ui": "0.1.6",
+    "@kupcad/wasm": "0.1.6"
   },
   "devDependencies": {
+    "@codemirror/language": "^6.13.1",
     "@codemirror/lint": "^6.9.7",
     "@codemirror/view": "^6.43.15",
     "@playwright/test": "^1.64.1",

package/src/Playground.svelte

@@ -10,8 +10,11 @@
   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: a
+  script, or a JSON file of the project, edited with nothing run and nothing in the viewer), 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';
@@ -37,12 +40,12 @@
   import { marksOf } from './marks.js';
   import { Runner } from './runner.js';
 
-  /** @import { Editor as EditorClass } from '@kupcad/editor' */
+  /** @import { Editor as EditorClass, EditorLanguage } from '@kupcad/editor' */
   /** @import { ExportFormat, Finding, ParamValues, Preview } from '@kupcad/protocol/types' */
   /** @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 +60,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 +78,7 @@
     viewerOptions = {},
     settings = localSettings(),
     onsource,
+    files,
     actions: hostActions,
     shortcuts = [],
     shortcutsOpen = $bindable(false),
@@ -109,6 +116,13 @@
    * 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));
+  /** What the document open is: a script, which runs, or a JSON file, which nothing runs of. */
+  let language = $state(/** @type {EditorLanguage} */ ('kupcad'));
+  const runs = $derived(language === 'kupcad');
   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[]} */ ([]));
@@ -125,7 +139,8 @@
   let runner = null;
 
   const header = $derived(ran?.preview.header ?? null);
-  const status = $derived(runStatusOf(header));
+  // None to say with nothing to run yet: a page that starts empty (a host with no file open)
+  const status = $derived(runs && (ran || value !== '') ? runStatusOf(header) : null);
   const problems = $derived(problemsOf(header));
   // Marked where they are in the script as it is: a run of another (older) script marks nothing
   const marks = $derived(marksOf(findings, ran?.source === value ? problems : []));
@@ -138,18 +153,19 @@
     core = kupcad ?? made;
     runner = new Runner(/** @type {KupcadApi} */ (core), {
       onfindings: (next, of) => {
-        if (of === value) findings = next;
+        if (runs && of === value) findings = next;
       },
       onpreview: (preview, of) => {
+        if (!runs) return;
         ran = { preview, source: of };
         notice = '';
         consoleLines = appendLines(consoleLines, linesOfRun(preview.header, name));
       },
       onerror: (error) => (notice = errorText(error)),
     });
-    runner.run(value, {}, { now: true });
+    if (value !== '') runner.run(value, {}, { now: true, files });
     return () => {
-      runner?.dispose();
+      runner?.stop();
       made?.terminate();
     };
   });
@@ -157,15 +173,65 @@
   /**
    * Puts `script` in the editor in place of the one there (the editor's undo takes that back),
    * and runs it at once on its own values (none the panel set for the last), its model framed
-   * whole.
+   * whole. In place of a JSON file, it is a document of its own.
    * @param {string} script another the page gives: an example, a script it opened
    */
   export function load(script) {
-    value = script;
+    if (!runs) {
+      language = 'kupcad';
+      restored = undefined;
+      documents += 1;
+    }
+    show(script);
+    runner?.run(script, {}, { now: true, files });
+  }
+
+  /**
+   * Opens a file 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). A script runs at once as `load` runs one; a JSON file (a
+   * package's kupcad.json or kupcad.lock, data a script imports) is edited with nothing run,
+   * nothing in the viewer.
+   * @param {string} text one of the page's files
+   * @param {unknown} [restore] the snapshot the page kept when it opened another
+   * @param {EditorLanguage} [of] what it is
+   */
+  export function open(text, restore, of = 'kupcad') {
+    restored = restore;
+    language = of;
+    documents += 1;
+    show(text);
+    if (of === 'kupcad') runner?.run(text, {}, { now: true, files });
+    else {
+      runner?.stop();
+      ran = null;
+    }
+  }
+
+  /** @param {string} text the document's, in place of the last one's, with none of its runs' */
+  function show(text) {
+    value = text;
     findings = [];
     overrides = {};
     loads += 1;
-    runner?.run(script, {}, { now: true });
+  }
+
+  /** 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() {
+    if (runs) 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 */
@@ -173,16 +239,16 @@
     consoleLines = appendLines(consoleLines, linesOfLog(line));
   }
 
-  /** @param {string} next the user's script */
+  /** @param {string} next the user's script (or JSON file) */
   function edited(next) {
     findings = [];
-    runner?.run(next, plainValues(overrides));
+    if (runs) 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 +260,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 +281,17 @@
   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}
+        {language}
+        onchange={edited}
+      />
+    {/key}
     {#if notice}<p class="notice" role="alert">{notice}</p>{/if}
   </section>
   <Splitter
@@ -352,7 +428,6 @@
     border-radius: var(--kc-radius);
     background: var(--kc-bg);
   }
-  /* A narrow page: the script over the model, the parameters under it */
   /* Narrow, the panes stacked, each at a height of its own, and the playground scrolled: the
      script a few lines, the model 4:3 of its width (at most 32em), the console and the
      parameters as tall as their lines */

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,19 +43,22 @@ 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. */
-  dispose() {
+  /**
+   * Stops the run waiting for the delay and the run under way: nothing comes of either. The
+   * next `run` runs again; a host done with the runner stops it and lets it go.
+   */
+  stop() {
     clearTimeout(this.#waiting);
     this.#running?.abort();
     this.#running = null;
@@ -63,8 +67,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 +78,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) {