@woosh/meep-engine 3.15.0 → 3.17.0

package/editor/view/particles/effect/ParticleCodeEditorView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleCodeEditorView.d.ts","sourceRoot":"","sources":["../../../../../editor/view/particles/effect/ParticleCodeEditorView.js"],"names":[],"mappings":"AAgDA;IA2DI;;;OAGG;IACH;QAFyG,MAAM,EAApG,OAAO,qDAAqD,EAAE,sBAAsB;OA6G9F;IAxGG,mBAAuC;IAIvC;;OAEG;IACH,QAFU,OAAO,qDAAqD,EAAE,sBAAsB,CAE1E;IAmGxB;;OAEG;IACH,wBAYC;IAED;;;;OAIG;IACH,gBAsCC;IAyGD;;;OAGG;IACH,iBAFW,MAAM,QAahB;IAsBD;;OAEG;IACH,eAyBC;IAcD,eAcC;;CACJ;iBA7dgB,8BAA8B"}

package/editor/view/particles/effect/ParticleCodeEditorView.js

@@ -0,0 +1,480 @@
+import LabelView from "../../../../src/view/common/LabelView.js";
+import EmptyView from "../../../../src/view/elements/EmptyView.js";
+import View from "../../../../src/view/View.js";
+import { PARTICLE_EFFECT_SOURCE } from "../../../particles/effect/ParticleEffectDocument.js";
+
+/**
+ * The code layer of the particle editor: the effect as instructions.
+ *
+ * Below the graph is a program — two streams of fixed-width VM instructions over a shared constant
+ * pool — and this is where an author sees and writes it. Two things it is for:
+ *
+ * - **reading what a graph became.** While the graph layer is authoritative the text here is that
+ *   graph's lowering, recomputed on every change and not editable. Register allocation, constant
+ *   interning, the order the compiler chose: all of it is right here, next to the graph that
+ *   produced it.
+ * - **writing instructions the graph cannot express.** `Lower to assembly` hands authority to the
+ *   text. From there the graph is still on screen and still editable, but the program is what is
+ *   written here — which is the only way to reach an encoding the node library has no node for.
+ *
+ * `Optimize` is the third thing, and it is a property of the effect rather than of this panel: it
+ * decides what the preview runs, and this is only where the switch happens to live. With it on, a
+ * graph's lowering is shown optimized, because that is then the program — see
+ * {@link ParticleEffectDocument#assemblyText} for what it does and does not do to hand-written text.
+ * The counts beside it are the point of a toggle nobody can see the effect of otherwise: what the
+ * program was, and what it became.
+ *
+ * Diagnostics come from the document, one per bad line, and the line each names is marked in the
+ * gutter. A program that does not assemble simply is not handed to the preview; the last good one
+ * keeps running, which is what makes typing into a live effect bearable.
+ *
+ * ## What is not on the action timeline
+ *
+ * Edits made here are not, deliberately. The graph layer's every edit is an {@link Action}, because
+ * a graph has no undo of its own; a textarea does, and a second one layered over it would fight it —
+ * two histories of the same text, diverging the first time a keystroke reached one and not the
+ * other. So Ctrl+Z in this pane is the browser's, over the text, and the editor's undo button steps
+ * the graph timeline.
+ */
+
+/** How long to wait after the last keystroke before assembling. @type {number} */
+const TYPING_SETTLE_MS = 250;
+
+/** Height of the header strip, px. @type {number} */
+const HEADER_HEIGHT = 32;
+
+/** Height of the status + problems strip, px. @type {number} */
+const FOOTER_HEIGHT = 120;
+
+export class ParticleCodeEditorView extends View {
+    /**
+     * @type {HTMLTextAreaElement}
+     */
+    #text;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #gutter;
+
+    /**
+     * @type {EmptyView}
+     */
+    #header;
+
+    /**
+     * @type {EmptyView}
+     */
+    #footer;
+
+    /**
+     * @type {EmptyView}
+     */
+    #editor;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #authority;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #toggle_label;
+
+    /**
+     * @type {HTMLInputElement}
+     */
+    #optimize;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #savings;
+
+    /**
+     * Pending assemble, so a burst of keystrokes costs one.
+     * @type {number}
+     */
+    #settle_timer = 0;
+
+    /**
+     * Set while this view is the one writing to the document, so its own change notification does
+     * not come back and replace the text the author is in the middle of typing.
+     * @type {boolean}
+     */
+    #writing = false;
+
+    /**
+     * @param {object} options
+     * @param {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument} options.effect
+     */
+    constructor({ effect }) {
+        super();
+
+        this.el = document.createElement('div');
+
+        this.addClass('ui-particle-code-editor');
+
+        /**
+         * @type {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument}
+         */
+        this.effect = effect;
+
+        this.#header = new EmptyView({ classList: ['header'] });
+        this.#editor = new EmptyView({ classList: ['editor'] });
+        this.#footer = new EmptyView({ classList: ['footer'] });
+
+        // Written straight to the element rather than through a LabelView: these two change on
+        // every refresh, and LabelView only follows an observable, on a frame throttle.
+        this.#authority = document.createElement('div');
+        this.#authority.classList.add('authority');
+
+        this.#header.el.appendChild(this.#authority);
+
+        this.#savings = document.createElement('div');
+        this.#savings.classList.add('savings');
+
+        this.#header.el.appendChild(this.#savings);
+
+        this.#optimize = document.createElement('input');
+        this.#optimize.setAttribute('type', 'checkbox');
+        this.#optimize.classList.add('optimize');
+
+        this.#optimize.addEventListener('change', () => this.effect.setOptimize(this.#optimize.checked));
+
+        const optimize_label = document.createElement('label');
+
+        optimize_label.classList.add('optimize-toggle');
+        optimize_label.title =
+            "Run the compiled program through the optimizer — the preview runs what this produces.";
+
+        optimize_label.appendChild(this.#optimize);
+        optimize_label.appendChild(document.createTextNode("Optimize"));
+
+        this.#header.el.appendChild(optimize_label);
+
+        const toggle = new EmptyView({ classList: ['toolbar-button', 'authority-toggle'] });
+
+        this.#toggle_label = document.createElement('span');
+        this.#toggle_label.classList.add('label');
+
+        toggle.el.appendChild(this.#toggle_label);
+        toggle.el.addEventListener('click', () => this.toggleAuthority());
+
+        this.#header.addChild(toggle);
+
+        this.#gutter = document.createElement('div');
+        this.#gutter.classList.add('gutter');
+
+        this.#text = document.createElement('textarea');
+        this.#text.classList.add('source');
+        this.#text.setAttribute('spellcheck', 'false');
+        this.#text.setAttribute('wrap', 'off');
+
+        this.#editor.el.appendChild(this.#gutter);
+        this.#editor.el.appendChild(this.#text);
+
+        // the gutter is a separate element, so it has to be scrolled with the text it numbers
+        this.#text.addEventListener('scroll', () => {
+            this.#gutter.scrollTop = this.#text.scrollTop;
+        });
+
+        this.#text.addEventListener('input', () => this.#scheduleCommit());
+
+        // Tab belongs to the program, not to the focus order: a code pane that tabs away on indent
+        // is not one anybody types into twice.
+        this.#text.addEventListener('keydown', event => {
+            if (event.key !== "Tab" || event.ctrlKey || event.altKey || event.metaKey) {
+                return;
+            }
+
+            if (this.#text.readOnly) {
+                // a lowering is not editable, and writing into it would show text that is not the
+                // program until the next refresh takes it away again
+                return;
+            }
+
+            event.preventDefault();
+
+            const start = this.#text.selectionStart;
+            const end = this.#text.selectionEnd;
+            const value = this.#text.value;
+
+            this.#text.value = `${value.slice(0, start)}    ${value.slice(end)}`;
+            this.#text.selectionStart = this.#text.selectionEnd = start + 4;
+
+            this.#scheduleCommit();
+        });
+
+        this.addChild(this.#header);
+        this.addChild(this.#editor);
+        this.addChild(this.#footer);
+
+        this.bindSignal(effect.on.changed, this.refresh, this);
+        this.on.linked.add(this.refresh, this);
+
+        this.bindSignal(this.size.onChanged, this.layout, this);
+        this.on.linked.add(this.layout, this);
+    }
+
+    /**
+     * Move authority between the layers, in whichever direction it currently is not.
+     */
+    toggleAuthority() {
+        if (this.effect.source === PARTICLE_EFFECT_SOURCE.ASSEMBLY) {
+            this.effect.useGraphs();
+            return;
+        }
+
+        const compilation = this.effect.lowerToAssembly();
+
+        if (compilation.program === null) {
+            // the graph does not compile, so there is nothing to hand over; the problems say why
+            this.refresh();
+        }
+    }
+
+    /**
+     * Redraw everything the document decides: the text, the gutter, the status line and the
+     * problems. Skipped while the author is typing into this very pane — the document's change came
+     * from here, and replacing the text would move the caret out from under them.
+     */
+    refresh() {
+        if (this.#writing) {
+            return;
+        }
+
+        // A change from elsewhere — the emitter inspector, an undo — is about to replace this text
+        // with the document's copy of it. Anything typed since the last settle is not in that copy
+        // yet, so it goes in first or it is lost.
+        if (this.#settle_timer !== 0) {
+            clearTimeout(this.#settle_timer);
+            this.#settle_timer = 0;
+
+            this.commit();
+        }
+
+        const authoring = this.effect.source === PARTICLE_EFFECT_SOURCE.ASSEMBLY;
+        const compilation = this.effect.compile();
+        const text = this.effect.assemblyText(compilation);
+
+        if (this.#text.value !== text) {
+            this.#text.value = text;
+        }
+
+        this.#text.readOnly = !authoring;
+
+        this.setClass('read-only', !authoring);
+
+        this.#authority.textContent = authoring
+            ? "Instructions are authoritative — the graph is not what runs."
+            : "Lowered from the graph. Read-only.";
+
+        this.#toggle_label.textContent = authoring ? "Back to graph" : "Lower to assembly";
+
+        this.#optimize.checked = this.effect.optimize;
+
+        this.#writeSavings(compilation);
+        this.#writeGutter(compilation.diagnostics);
+        this.#writeFooter(compilation);
+    }
+
+    /**
+     * What the optimizer did, in the two numbers that decide whether it was worth it.
+     *
+     * Instructions are what the VM steps through and registers are what decides which interpreter
+     * runs it: past `PARTICLE_VM_FAST_REGISTER_SLOTS` the whole system falls back to the wide VM,
+     * which works and is far slower. So those are the pair. Blank when the box is not ticked: there
+     * is nothing to compare a program against itself with.
+     *
+     * @param {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectCompilation} compilation
+     */
+    #writeSavings(compilation) {
+        const { program, unoptimized } = compilation;
+
+        if (!this.effect.optimize || program === null || program === unoptimized) {
+            this.#savings.textContent = "";
+            return;
+        }
+
+        const before = unoptimized.init_instruction_count + unoptimized.update_instruction_count;
+        const after = program.init_instruction_count + program.update_instruction_count;
+
+        this.#savings.textContent =
+            `${before} → ${after} instr · ${unoptimized.register_count} → ${program.register_count} regs`;
+    }
+
+    /**
+     * @param {Array<{scope: string, line: number, message: string}>} diagnostics
+     */
+    #writeGutter(diagnostics) {
+        const lines = this.#text.value.split("\n").length;
+
+        const bad = new Set(
+            diagnostics.filter(d => d.scope === "assembly" && d.line > 0).map(d => d.line)
+        );
+
+        const fragment = document.createDocumentFragment();
+
+        for (let line = 1; line <= lines; line++) {
+            const element = document.createElement('div');
+
+            element.classList.add('line');
+            element.textContent = String(line);
+
+            if (bad.has(line)) {
+                element.classList.add('bad');
+            }
+
+            fragment.appendChild(element);
+        }
+
+        this.#gutter.replaceChildren(fragment);
+        this.#gutter.scrollTop = this.#text.scrollTop;
+    }
+
+    /**
+     * @param {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectCompilation} compilation
+     */
+    #writeFooter(compilation) {
+        this.#footer.removeAllChildren();
+
+        const program = compilation.program;
+
+        const status = new EmptyView({ classList: ['status'] });
+
+        if (program === null) {
+            status.addChild(new LabelView("does not assemble", { classList: ['bad'] }));
+        } else {
+            // "const words" rather than "const": the pool is addressed by word rather than by
+            // vec4, so the number is four times what a reader counting vectors would expect it to
+            // be, and the shorter label would have them reading it as vectors.
+            status.addChild(new LabelView(
+                `${program.init_instruction_count} init · ${program.update_instruction_count} update `
+                + `· ${program.constant_word_count} const words · ${program.register_count} regs`,
+                { classList: ['counts'] }
+            ));
+        }
+
+        this.#footer.addChild(status);
+
+        const relevant = compilation.diagnostics.filter(
+            diagnostic => this.effect.source === PARTICLE_EFFECT_SOURCE.ASSEMBLY
+                ? diagnostic.scope === "assembly" || diagnostic.scope === "effect"
+                : true
+        );
+
+        for (const diagnostic of relevant) {
+            const entry = new EmptyView({ classList: ['problem', diagnostic.severity] });
+
+            const where = diagnostic.line > 0
+                ? `line ${diagnostic.line}`
+                : (diagnostic.node >= 0 ? `${diagnostic.scope}: node ${diagnostic.node}` : diagnostic.scope);
+
+            entry.addChild(new LabelView(where, { classList: ['where'] }));
+            entry.addChild(new LabelView(diagnostic.message, { classList: ['message'] }));
+
+            if (diagnostic.line > 0) {
+                entry.el.addEventListener('click', () => this.revealLine(diagnostic.line));
+            }
+
+            this.#footer.addChild(entry);
+        }
+    }
+
+    /**
+     * Put the caret at the start of a line and scroll it into view.
+     * @param {number} line 1-based
+     */
+    revealLine(line) {
+        const lines = this.#text.value.split("\n");
+
+        let offset = 0;
+
+        for (let i = 0; i < Math.min(line - 1, lines.length); i++) {
+            offset += lines[i].length + 1;
+        }
+
+        this.#text.focus();
+        this.#text.setSelectionRange(offset, offset + (lines[line - 1]?.length ?? 0));
+    }
+
+    /**
+     * Push the text into the document once the author stops typing.
+     *
+     * Every keystroke would be a recompile and, downstream, a rebuilt emitter — so a burst costs one
+     * rather than one each. Nothing is lost by waiting: an unassembled buffer is not a program, and
+     * the preview keeps running the last one that was.
+     */
+    #scheduleCommit() {
+        if (this.effect.source !== PARTICLE_EFFECT_SOURCE.ASSEMBLY) {
+            return;
+        }
+
+        clearTimeout(this.#settle_timer);
+
+        this.#settle_timer = setTimeout(() => {
+            this.#settle_timer = 0;
+            this.commit();
+        }, TYPING_SETTLE_MS);
+    }
+
+    /**
+     * Push the text into the document now, without waiting for typing to settle.
+     */
+    commit() {
+        if (this.effect.source !== PARTICLE_EFFECT_SOURCE.ASSEMBLY) {
+            return;
+        }
+
+        if (this.effect.assembly === this.#text.value) {
+            return;
+        }
+
+        this.effect.assembly = this.#text.value;
+
+        // The document's change comes back here; `#writing` keeps it from replacing the text under
+        // the caret, while everything else downstream still hears about it.
+        this.#writing = true;
+
+        try {
+            this.effect.touch();
+        } finally {
+            this.#writing = false;
+        }
+
+        const compilation = this.effect.compile();
+
+        this.#writeGutter(compilation.diagnostics);
+        this.#writeFooter(compilation);
+    }
+
+    unlink() {
+        if (this.#settle_timer !== 0) {
+            clearTimeout(this.#settle_timer);
+            this.#settle_timer = 0;
+
+            // an edit made in the last moments before the pane goes away is still the author's
+            this.commit();
+        }
+
+        super.unlink();
+    }
+
+    layout() {
+        const width = this.size.x;
+        const height = this.size.y;
+
+        const editor_height = Math.max(0, height - HEADER_HEIGHT - FOOTER_HEIGHT);
+
+        this.#header.position.set(0, 0);
+        this.#header.size.set(width, HEADER_HEIGHT);
+
+        this.#editor.position.set(0, HEADER_HEIGHT);
+        this.#editor.size.set(width, editor_height);
+
+        this.#footer.position.set(0, HEADER_HEIGHT + editor_height);
+        this.#footer.size.set(width, FOOTER_HEIGHT);
+    }
+}

package/editor/view/particles/effect/ParticleCurveEditorView.d.ts

@@ -0,0 +1,20 @@
+export class ParticleCurveEditorView extends View {
+    /**
+     * @param {object} options
+     * @param {function():object} options.read the parameter's current value
+     * @param {function(object):void} options.write commit a new value
+     */
+    constructor({ read, write }: {
+        read: () => object;
+        write: (arg0: object) => void;
+    });
+    el: HTMLDivElement;
+    /**
+     * Re-read the parameter and redraw.
+     */
+    refresh(): void;
+    render(): void;
+    #private;
+}
+import View from "../../../../src/view/View.js";
+//# sourceMappingURL=ParticleCurveEditorView.d.ts.map

package/editor/view/particles/effect/ParticleCurveEditorView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleCurveEditorView.d.ts","sourceRoot":"","sources":["../../../../../editor/view/particles/effect/ParticleCurveEditorView.js"],"names":[],"mappings":"AAgEA;IA6CI;;;;OAIG;IACH;QAHsC,IAAI,QAApB,MAAM;QACc,KAAK,SAA3B,MAAM,KAAE,IAAI;OAiF/B;IAzEG,mBAAuC;IA2E3C;;OAEG;IACH,gBAcC;IAgRD,eAiEC;;CACJ;iBA/hBgB,8BAA8B"}