dewdrop-sdk 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dewdrop-sdk",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Build a three.js game for Dewdrop: the Vite plugin, model calls, multiplayer, saves and voice.",
   "license": "MIT",
   "type": "module",

package/src/evaluate.js

@@ -0,0 +1,57 @@
+// A page the dev server serves offers `dewdrop.evaluate(code)`, as a dev
+// version's page on Dewdrop does, so one script drives the game in both.
+// `code`, a string or a function sent as its source text called with
+// nothing, runs at the page's top level, as the browser's console runs
+// what is typed into it: what the game puts on `globalThis` is in reach and
+// its modules' own bindings are not. The call resolves with the value the
+// code came to as JSON carries it, a promise's once it settles, `undefined`
+// for none, or rejects with an Error carrying the text of what the code
+// threw; code, waiting calls and values past what Dewdrop takes are
+// refused in Dewdrop's words. The plugin puts `evaluateScript` in the
+// page's head; it is `offerEvaluate`'s own text, so the function imports
+// nothing and is written without a `<`.
+
+// What Dewdrop takes: the bytes of a call's code, the calls waiting at
+// once, and the bytes of a value's JSON.
+export const LIMITS = Object.freeze({ code: 32764, waiting: 16, value: 65530 });
+
+// Offers `dewdrop.evaluate` on `scope`, the page's window, within `limits`.
+// Assigned rather than defined, since the game shares the window here.
+export function offerEvaluate(scope, limits) {
+  const run = scope.eval;
+  const encoder = new scope.TextEncoder();
+  const describe = (error) => {
+    try {
+      return error !== null && typeof error === 'object' && typeof error.stack === 'string' ? error.stack : String(error);
+    } catch {
+      return '[unprintable]';
+    }
+  };
+  let waiting = 0;
+  async function evaluate(code) {
+    if (typeof code === 'function') code = `(${code})()`;
+    else if (typeof code !== 'string') throw new TypeError('dewdrop.evaluate takes a string or a function');
+    if (waiting >= limits.waiting) throw new RangeError(`dewdrop.evaluate has ${limits.waiting} calls waiting already`);
+    const bytes = encoder.encode(code).length;
+    if (bytes > limits.code) throw new RangeError(`dewdrop.evaluate takes code of at most ${limits.code} bytes, not ${bytes}`);
+    waiting += 1;
+    let text;
+    try {
+      text = JSON.stringify(await run(code));
+    } catch (error) {
+      throw new Error(describe(error));
+    } finally {
+      waiting -= 1;
+    }
+    if (text === undefined) return undefined;
+    const length = encoder.encode(text).length;
+    if (length > limits.value) throw new Error(`the value is ${length} bytes as JSON, more than the ${limits.value} an answer carries`);
+    return JSON.parse(text);
+  }
+  scope.dewdrop = Object.freeze({ evaluate });
+}
+
+// The script the plugin puts in a page the dev server serves.
+export function evaluateScript() {
+  return `(${offerEvaluate})(window, ${JSON.stringify(LIMITS)});`;
+}

package/src/index.js

@@ -5,7 +5,8 @@
 // runs, `clients`, in that backend, over its port back, and `saves` into
 // the browser's own storage, which the plugin's script empties as each
 // page loads; `session` says when a session ends ahead of time, which here
-// none does; and `voice` reads the microphone through the browser's own
+// none does, and lets a game end its player's session, which here ends
+// nothing; and `voice` reads the microphone through the browser's own
 // audio worklet, into the chunks a game gets on Dewdrop.
 export { llm } from './llm.js';
 export { backend } from './backend.js';

package/src/session.js

@@ -1,17 +1,31 @@
 // `session` on a developer's machine. On Dewdrop a session can end ahead of
-// time — for maintenance, a newer version of its game published, or its
-// player idle for fifteen minutes — and hears of it first, up to fifteen
-// minutes before, a minute for an idle player: `session.ending` is
-// `{at, reason}`, `at` in milliseconds since the epoch as `Date.now()` counts
-// and `reason` `'restart'`, `'update'` or `'idle'`, and an `ending` event
-// fires each time it changes, its withdrawal to null included, so a game can
-// save and say so. `npm run dev` ends no session ahead of time, so here `ending`
-// stays null and the event never fires; a game tries its handler by calling
-// it.
-import { defineHandlers } from './net.js';
+// time — for maintenance, a newer version of its game published, its player
+// idle for fifteen minutes, its player away for ten — the page hidden, or
+// another game of theirs showing — or its player choosing to play in
+// another tab — and hears of it first, up to fifteen minutes before, a
+// minute for an idle or an away player, and as it ends for a player playing
+// elsewhere: `session.ending` is `{at, reason}`, `at` in milliseconds since
+// the epoch as `Date.now()` counts and `reason` `'restart'`, `'update'`,
+// `'idle'`, `'away'`, `'elsewhere'` or `'exit'`, and an `ending` event fires
+// each time it changes, its withdrawal to null included, so a game can save
+// and say so. A game ends its player's session itself with
+// `session.exit()`, which on Dewdrop takes the player back to Dewdrop's
+// home page while the room's other players play on, the game hearing
+// `'exit'` as it goes; a backend has no player to send anywhere, so there it
+// throws NotSupportedError. `npm run dev` ends no session, so here `ending`
+// stays null and the event never fires, a game trying its handler by
+// calling it, and `exit()` ends nothing: the console says so, once.
+import { defineHandlers, side } from './net.js';
 
+let told = false;
 class Session extends EventTarget {
   get ending() { return null; }
+  exit() {
+    if (side.backend) throw new DOMException('session.exit is unavailable in a backend', 'NotSupportedError');
+    if (told) return;
+    told = true;
+    console.info('[dewdrop] session.exit(): on Dewdrop this ends the session and takes the player back to Dewdrop’s home page; npm run dev keeps the game running');
+  }
 }
 defineHandlers(Session.prototype, ['ending']);
 

package/src/vite.js

@@ -6,8 +6,9 @@
 // with a backend gets a second chunk beside it, `backend.js`. In dev: the
 // route that carries a model call to its provider with the key from the
 // developer's environment, the host that runs the game's backend for the
-// tabs that join it, and the script that starts each page's storage empty
-// for the game's saves. Every other build is untouched. The plugin
+// tabs that join it, and the scripts that start each page's storage empty
+// for the game's saves and offer `dewdrop.evaluate`. Every other build is
+// untouched. The plugin
 // imports nothing from Vite itself, so it works linked from a checkout as
 // well as installed, on Vite 3 through 8.
 import { existsSync, readFileSync } from 'node:fs';
@@ -15,6 +16,7 @@ import { resolve } from 'node:path';
 import { ASSETS_DIR, BACKEND_FILE, ENTRY_FILE, PAGE_FILE, detectViteMajor, openPage, outputOptions } from './build.js';
 import { createLlmMiddleware } from './dev.js';
 import { loadKeys } from './env.js';
+import { evaluateScript } from './evaluate.js';
 import { freshScript } from './fresh.js';
 import { DEV_ROUTE } from './route.js';
 import { createBackendHost } from './serve.js';
@@ -140,14 +142,15 @@ export default function dew() {
       },
     },
     // The page the dev server serves is told whether the game has a
-    // backend, which the client's `backend` reads before it joins, and
-    // starts with its storage empty, as on Dewdrop, from a script first
-    // in the page, before anything of its own.
+    // backend, which the client's `backend` reads before it joins, starts
+    // with its storage empty, as on Dewdrop, and offers `dewdrop.evaluate`,
+    // as a dev version's page does, from a script first in the page,
+    // before anything of its own.
     // A build's page, which no dev server serves, is left alone.
     transformIndexHtml(html) {
       if (!serving) return undefined;
       return {
-        html: withFirstScript(html, freshScript(game)),
+        html: withFirstScript(html, freshScript(game) + evaluateScript()),
         tags: [{ tag: 'meta', attrs: { name: 'dew-backend', content: entry === null ? 'no' : 'yes' }, injectTo: 'head' }],
       };
     },