@kupcad/playground 0.1.5 → 0.1.7

package/README.md

@@ -26,20 +26,22 @@ browser IDE embed; 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.
+* **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
@@ -53,8 +55,8 @@ browser IDE embed; it keeps nothing of the page's.
   resize them (`@kupcad/ui`'s `Splitter`), and the toolbar's Parameters button hides the
   parameters for the model's width; the sizes, and what is hidden or folded, are kept in
   `settings`, by default the page's localStorage (`localSettings`, the `playground.*` keys), and
-  how the view looks too (the pane's `view.*` keys), all followed as they are set. A page 800px
-  wide or less stacks the panes, each at a height of its own (the script a few lines, the model
+  how the view looks too (the pane's `view.*` keys), all followed as they are set. Given 800px
+  or less (a phone, or a column of a page: it goes by its own width) it stacks the panes, each at a height of its own (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), and
   the playground scrolls; on a phone the view's panel is under the model (`ViewerPane`'s).
 * **The console** (`@kupcad/ui`'s `ConsolePanel`, under the model): each run, what it printed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kupcad/playground",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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.5",
-    "@kupcad/protocol": "0.1.5",
-    "@kupcad/ui": "0.1.5",
-    "@kupcad/wasm": "0.1.5"
+    "@kupcad/editor": "0.1.7",
+    "@kupcad/protocol": "0.1.7",
+    "@kupcad/ui": "0.1.7",
+    "@kupcad/wasm": "0.1.7"
   },
   "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,7 +10,8 @@
   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`, or `open` for another document, with an undo history of its own), and
+  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`).
@@ -39,7 +40,7 @@
   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' */
@@ -119,6 +120,9 @@
   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[]} */ ([]));
@@ -135,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 : []));
@@ -148,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, files });
+    if (value !== '') runner.run(value, {}, { now: true, files });
     return () => {
-      runner?.dispose();
+      runner?.stop();
       made?.terminate();
     };
   });
@@ -167,28 +173,47 @@
   /**
    * 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;
-    findings = [];
-    overrides = {};
-    loads += 1;
+    if (!runs) {
+      language = 'kupcad';
+      restored = undefined;
+      documents += 1;
+    }
+    show(script);
     runner?.run(script, {}, { now: true, files });
   }
 
   /**
-   * Opens `script` in the editor in place of the one there as another document: the editor made
+   * 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), and run at once as `load` runs one.
-   * @param {string} script one of the page's scripts
+   * `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(script, restore) {
+  export function open(text, restore, of = 'kupcad') {
     restored = restore;
+    language = of;
     documents += 1;
-    load(script);
+    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;
   }
 
   /** The editor as it is now, its undo history with it, for `open` to give back: plain JSON. */
@@ -201,7 +226,7 @@
    * (`files`), which the page knows of and it doesn't.
    */
   export function run() {
-    runner?.run(value, plainValues(overrides), { now: true, files });
+    if (runs) runner?.run(value, plainValues(overrides), { now: true, files });
   }
 
   /** Puts the focus in the editor: a script the page made, to be written. */
@@ -214,10 +239,10 @@
     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), { files });
+    if (runs) runner?.run(next, plainValues(overrides), { files });
     onsource?.(next);
   }
 
@@ -249,112 +274,121 @@
   }
 </script>
 
-<div
-  class="kc-playground"
-  bind:clientWidth={width}
-  style:--editor-width="{editorWidth}px"
-  style:--params-width="{paramsWidth}px"
->
-  <section class="code" aria-label="Script">
-    {#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
-    bind:size={editorWidth}
-    min={240}
-    max={width > 0 ? width - (paramsShown ? paramsWidth : 0) - MIN_VIEW : undefined}
-    label="Resize the script"
-    onchange={(size) => settings.set(KEYS.editor, size)}
-  />
-  <section class="view" aria-label="Model">
-    <div class="model">
-      <ViewerPane
-        model={ran?.preview.model ?? null}
-        subject="script {loads}"
-        options={viewerOptions}
-        bind:panel={() => panelOpen, (open) => settings.set(KEYS.panelOpen, open)}
-        {status}
-        {problems}
-        onproblem={reveal}
-        onscreenshot={screenshot}
-        {settings}
-        {shortcuts}
-        bind:shortcutsOpen
-      >
-        {#snippet actions()}
-          <ExportMenu kind={ran?.preview.model.kind ?? 'none'} onexport={exportChosen} />
-          {@render hostActions?.()}
-        {/snippet}
-        {#snippet toggles()}
-          {#if header && parameters.length > 0}
-            <button
-              type="button"
-              class="kc-control"
-              aria-controls="{id}-params"
-              aria-expanded={paramsOpen}
-              onclick={() => settings.set(KEYS.paramsOpen, !paramsOpen)}
-            >
-              Parameters
-            </button>
-          {/if}
-        {/snippet}
-      </ViewerPane>
-    </div>
-    {#if consoleOpen}
-      <Splitter
-        between="rows"
-        pane="after"
-        bind:size={consoleHeight}
-        min={48}
-        label="Resize the console"
-        onchange={(size) => settings.set(KEYS.console, size)}
-      />
-    {/if}
-    <ConsolePanel
-      lines={consoleLines}
-      height={consoleHeight}
-      bind:open={() => consoleOpen, (open) => settings.set(KEYS.open, open)}
-      onreveal={reveal}
-      onclear={() => (consoleLines = [])}
+<!-- The box the playground is laid out by: its own width, wide or a column of a page -->
+<div class="kc-playground-box">
+  <div
+    class="kc-playground"
+    bind:clientWidth={width}
+    style:--editor-width="{editorWidth}px"
+    style:--params-width="{paramsWidth}px"
+  >
+    <section class="code" aria-label="Script">
+      {#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
+      bind:size={editorWidth}
+      min={240}
+      max={width > 0 ? width - (paramsShown ? paramsWidth : 0) - MIN_VIEW : undefined}
+      label="Resize the script"
+      onchange={(size) => settings.set(KEYS.editor, size)}
     />
-  </section>
-  {#if header && parameters.length > 0}
-    {#if paramsOpen}
-      <Splitter
-        pane="after"
-        bind:size={paramsWidth}
-        min={200}
-        max={640}
-        label="Resize the parameters"
-        onchange={(size) => settings.set(KEYS.params, size)}
+    <section class="view" aria-label="Model">
+      <div class="model">
+        <ViewerPane
+          model={ran?.preview.model ?? null}
+          subject="script {loads}"
+          options={viewerOptions}
+          bind:panel={() => panelOpen, (open) => settings.set(KEYS.panelOpen, open)}
+          {status}
+          {problems}
+          onproblem={reveal}
+          onscreenshot={screenshot}
+          {settings}
+          {shortcuts}
+          bind:shortcutsOpen
+        >
+          {#snippet actions()}
+            <ExportMenu kind={ran?.preview.model.kind ?? 'none'} onexport={exportChosen} />
+            {@render hostActions?.()}
+          {/snippet}
+          {#snippet toggles()}
+            {#if header && parameters.length > 0}
+              <button
+                type="button"
+                class="kc-control"
+                aria-controls="{id}-params"
+                aria-expanded={paramsOpen}
+                onclick={() => settings.set(KEYS.paramsOpen, !paramsOpen)}
+              >
+                Parameters
+              </button>
+            {/if}
+          {/snippet}
+        </ViewerPane>
+      </div>
+      {#if consoleOpen}
+        <Splitter
+          between="rows"
+          pane="after"
+          bind:size={consoleHeight}
+          min={48}
+          label="Resize the console"
+          onchange={(size) => settings.set(KEYS.console, size)}
+        />
+      {/if}
+      <ConsolePanel
+        lines={consoleLines}
+        height={consoleHeight}
+        bind:open={() => consoleOpen, (open) => settings.set(KEYS.open, open)}
+        onreveal={reveal}
+        onclear={() => (consoleLines = [])}
       />
-    {/if}
-    <!-- Hidden, not gone: what its fields hold stays, and the toggle has it to control -->
-    <aside class="params" id="{id}-params" aria-label="Parameters" hidden={!paramsOpen}>
-      <!-- Made again for each script loaded: no field keeps what was typed in the last's -->
-      {#key loads}
-        <ParamsPanel
-          schema={header.params.schema}
-          values={header.params.values}
-          error={header.error}
-          bind:overrides
-          onchange={valuesChanged}
+    </section>
+    {#if header && parameters.length > 0}
+      {#if paramsOpen}
+        <Splitter
+          pane="after"
+          bind:size={paramsWidth}
+          min={200}
+          max={640}
+          label="Resize the parameters"
+          onchange={(size) => settings.set(KEYS.params, size)}
         />
-      {/key}
-    </aside>
-  {/if}
+      {/if}
+      <!-- Hidden, not gone: what its fields hold stays, and the toggle has it to control -->
+      <aside class="params" id="{id}-params" aria-label="Parameters" hidden={!paramsOpen}>
+        <!-- Made again for each script loaded: no field keeps what was typed in the last's -->
+        {#key loads}
+          <ParamsPanel
+            schema={header.params.schema}
+            values={header.params.values}
+            error={header.error}
+            bind:overrides
+            onchange={valuesChanged}
+          />
+        {/key}
+      </aside>
+    {/if}
+  </div>
 </div>
 
 <style>
+  .kc-playground-box {
+    height: 100%;
+    min-height: 0;
+    container-type: inline-size;
+  }
   .kc-playground {
     display: flex;
     height: 100%;
@@ -402,11 +436,10 @@
     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 */
-  @media (max-width: 800px) {
+  /* Narrow (a phone, a column of a page), 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 */
+  @container (max-width: 800px) {
     .kc-playground {
       flex-direction: column;
       overflow-y: auto;

package/src/runner.js

@@ -54,8 +54,11 @@ export class Runner {
     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;