dewdrop-sdk 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dewdrop Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# dewdrop-sdk
+
+The package that builds a three.js game for Dewdrop and runs it locally: the
+Vite plugin, model calls and multiplayer.
+
+## Set up
+
+In a Vite 6 or later project:
+
+```sh
+npm install -D dewdrop-sdk
+npm install --save-exact three@0.185.1
+```
+
+```js
+// vite.config.js
+import dew from 'dewdrop-sdk/vite';
+export default { plugins: [dew()] };
+```
+
+`npx dewctl init` sets up a new game this way, with the Dewdrop CLI beside it.
+
+## Docs
+
+How to build your game, from the look to model calls, multiplayer and what
+works on Dewdrop, is in the docs: https://alpha.dewdrop.world/docs
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "dewdrop-sdk",
+  "version": "0.3.1",
+  "description": "Build a three.js game for Dewdrop: the Vite plugin, model calls and multiplayer.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./vite": "./src/vite.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "peerDependencies": {
+    "vite": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  }
+}

package/src/backend-host.js

@@ -0,0 +1,17 @@
+// The thread the plugin runs a project's backend.js in: it serves the
+// clients over the port to the plugin, tells the model call where the dev
+// server is, loads the game's backend, whose `dewdrop-sdk` resolves to this
+// package as the plugin's own does, and only then starts delivering what
+// the clients sent, so the first join reaches the handlers the module
+// registered. A throw while the backend evaluates ends the thread, which
+// the host reports and stops; a throw in a handler or a timer after that
+// is logged and the backend goes on.
+import { parentPort, workerData } from 'node:worker_threads';
+import { pathToFileURL } from 'node:url';
+import { attachClients } from './clients.js';
+
+process.env.DEW_DEV_ORIGIN = workerData.origin;
+const start = attachClients(parentPort);
+await import(pathToFileURL(workerData.entry).href);
+process.on('uncaughtException', (error) => console.error(`uncaught ${error?.stack ?? error}`));
+start();

package/src/backend.js

@@ -0,0 +1,87 @@
+// `backend` on a developer's machine: the client's side of the messages a
+// game exchanges with its backend, carried here over the Vite dev server's
+// socket to the backend.js the plugin runs beside it, so a game's code is
+// the same here and on Dewdrop. A frame's sends leave together at the next
+// animation frame; what the backend sends arrives at the next animation
+// frame as `message` events, or one `gap` where the inbox dropped messages
+// past its cap. The page's URL says which room the tab joins and under
+// what name; on Dewdrop the game's page says which room, and the name is
+// the player's username.
+import { MAX_NET_CLIENT_FRAME_BYTES, createInbox, createOutbox, defineHandlers, label, side, unpack } from './net.js';
+import { NO_CHANNEL } from './route.js';
+
+let channel = null;
+let hasBackend = false;
+let frame = null;
+const outbox = createOutbox(MAX_NET_CLIENT_FRAME_BYTES);
+const inbox = createInbox();
+let flushing = false;
+let draining = false;
+
+class Backend extends EventTarget {
+  send(data) {
+    if (side.backend) throw new DOMException('backend is unavailable in a backend', 'NotSupportedError');
+    if (channel === null) throw new TypeError(`backend.send: ${NO_CHANNEL}`);
+    if (!hasBackend) throw new DOMException('backend is unavailable: this game has no backend.js', 'NotSupportedError');
+    outbox.push('backend.send', 0, data);
+    if (flushing) return;
+    flushing = true;
+    frame(() => {
+      flushing = false;
+      channel.send('dew:send', { items: outbox.flush() });
+    });
+  }
+}
+defineHandlers(Backend.prototype, ['message', 'gap']);
+
+export const backend = new Backend();
+
+function deliver() {
+  draining = false;
+  for (const record of inbox.drain()) {
+    backend.dispatchEvent(record.kind === 'gap' ? new Event('gap') : new MessageEvent('message', { data: unpack(record) }));
+  }
+}
+
+// A room as Dewdrop names one: lowercase letters, digits, and dashes, up
+// to 32, a name typed in capitals or with space around it being the same
+// room; anything else names no room.
+const ROOM_KEY = /^[a-z0-9-]{1,32}$/;
+function room(text) {
+  const key = text.trim().toLowerCase();
+  return ROOM_KEY.test(key) ? key : '';
+}
+
+// A name as Dewdrop takes one: control characters removed, trimmed, then
+// cut to the label's cap.
+function name(text) {
+  return label(text.replace(/\p{Cc}/gu, '').trim());
+}
+
+// Where a page's URL joins its tab: the room `?room=` names and the name
+// `?player=` names, each held to Dewdrop's rule — the empty room without
+// one, or with one that names no room; unnamed without a name, or with one
+// that is nothing but space and control characters.
+export function joining(search) {
+  const params = new URLSearchParams(search);
+  return { room: room(params.get('room') ?? ''), player: name(params.get('player') ?? '') };
+}
+
+// Joins the backend of `room` under `player`'s name over `hot`, the page's
+// hot context, once the plugin has said whether the game has one:
+// `present` is that, `schedule` runs a function at the next animation
+// frame. Without a plugin there is no channel, and `send` says so.
+export function attachBackend(hot, { channel: routed, hasBackend: present, frame: schedule, room = '', player = '' }) {
+  if (!routed) return;
+  channel = hot;
+  hasBackend = present;
+  frame = schedule;
+  if (!present) return;
+  hot.on('dew:recv', ({ items }) => {
+    inbox.receive(items.map((item) => ({ kind: 'message', ...item })));
+    if (draining) return;
+    draining = true;
+    frame(deliver);
+  });
+  hot.send('dew:join', { room, player });
+}

package/src/build.js

@@ -0,0 +1,55 @@
+// What a Dewdrop build asks of the bundler: one chunk of ES modules,
+// named in the words of the Vite the project has installed.
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// The Dewdrop build's entry: the one chunk, written as `main.js` at the
+// top of the output beside the index.html a browser would open, so the
+// built folder is ready to upload as it is; a game with a backend gets a
+// second chunk beside it, `backend.js`.
+export const ENTRY_FILE = 'main.js';
+export const BACKEND_FILE = 'backend.js';
+
+// The page a browser would open, as the build emits it beside the entry.
+export const PAGE_FILE = 'index.html';
+
+// Where Vite writes the files it emits — the stylesheets a game imports,
+// and the images, fonts, and models it imports above the inline limit —
+// `ui/`, where what the page shows must be on Dewdrop.
+export const ASSETS_DIR = 'ui';
+
+// The block that opens the built page in the document, as a browser would
+// have before the entry ran: on Dewdrop the game starts from the entry
+// rather than the page, so the page's head (the stylesheets Vite linked,
+// the title) and its body (a loading screen, a HUD's containers) reach the
+// document through the entry, the page's scripts dropped.
+export function openPage(html) {
+  return `{ const page = new DOMParser().parseFromString(${JSON.stringify(html)}, 'text/html'); `
+    + `for (const script of page.querySelectorAll('script')) script.remove(); `
+    + `document.head.append(...page.head.childNodes); document.body.append(...page.body.childNodes); }\n`;
+}
+
+// The output settings for one chunk of ES modules named as the Dewdrop
+// build's entry: Rollup, which Vite used through 7, folds dynamic imports
+// with `inlineDynamicImports`; Rolldown, under Vite 8, calls the same
+// thing `codeSplitting: false` and warns about the old name.
+export function outputOptions(viteMajor, entryFileNames = ENTRY_FILE) {
+  const oneChunk = viteMajor !== undefined && viteMajor >= 8
+    ? { codeSplitting: false }
+    : { inlineDynamicImports: true };
+  return { format: 'es', entryFileNames, ...oneChunk };
+}
+
+// The major version of the Vite the project at `root` has installed, or
+// undefined when none can be found.
+export function detectViteMajor(root) {
+  try {
+    const require = createRequire(pathToFileURL(join(root, 'package.json')));
+    const { version } = JSON.parse(readFileSync(require.resolve('vite/package.json'), 'utf8'));
+    return Number(version.split('.')[0]);
+  } catch {
+    return undefined;
+  }
+}

package/src/clients.js

@@ -0,0 +1,95 @@
+// `clients` on a developer's machine: the backend's side of the messages a
+// game exchanges with its clients, run by the plugin in a thread of the
+// dev server with a port to the plugin, which carries each message over
+// the socket to the tab it names. The thread ticks sixty times a second:
+// each tick delivers what the clients sent as `join`, `leave`, `message`,
+// and `gap` events — a join naming the player's label — runs the
+// animation-frame callbacks, and sends the frame's messages.
+import { MAX_NET_BACKEND_FRAME_BYTES, NET_TICK_MS, ClientEvent, createInbox, createOutbox, defineHandlers, side, unpack } from './net.js';
+
+const outbox = createOutbox(MAX_NET_BACKEND_FRAME_BYTES);
+const inbox = createInbox();
+let port = null;
+
+// A client number as the backend was told it: a whole number from one.
+function number(op, value) {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 0xffffffff) {
+    throw new TypeError(`${op}: client is not a client number`);
+  }
+  return value;
+}
+
+class Clients extends EventTarget {
+  send(to, data) {
+    if (port === null) throw new DOMException('clients is unavailable in a client', 'NotSupportedError');
+    outbox.push('clients.send', number('clients.send', to), data);
+  }
+  broadcast(data) {
+    if (port === null) throw new DOMException('clients is unavailable in a client', 'NotSupportedError');
+    outbox.push('clients.broadcast', 0, data);
+  }
+}
+defineHandlers(Clients.prototype, ['join', 'leave', 'message', 'gap']);
+
+export const clients = new Clients();
+
+// The animation-frame callbacks, run once each tick; installed when the
+// thread has none of its own.
+const callbacks = new Map();
+let nextCallback = 1;
+function requestAnimationFrame(fn) {
+  if (typeof fn !== 'function') throw new TypeError("Failed to execute 'requestAnimationFrame': parameter 1 is not of type 'Function'");
+  const id = nextCallback++;
+  callbacks.set(id, fn);
+  return id;
+}
+function cancelAnimationFrame(id) {
+  callbacks.delete(id);
+}
+
+function frame() {
+  for (const record of inbox.drain()) {
+    switch (record.kind) {
+      case 'join': clients.dispatchEvent(new ClientEvent('join', { client: record.client, player: record.player ?? '' })); break;
+      case 'leave': clients.dispatchEvent(new ClientEvent('leave', { client: record.client })); break;
+      case 'message': clients.dispatchEvent(new ClientEvent('message', { client: record.client, data: unpack(record) })); break;
+      default: clients.dispatchEvent(new Event('gap'));
+    }
+  }
+  const due = [...callbacks.values()];
+  callbacks.clear();
+  const now = performance.now();
+  for (const fn of due) {
+    // A callback that throws is logged and the rest run, as in a browser.
+    try {
+      fn(now);
+    } catch (error) {
+      console.error(`uncaught ${error?.stack ?? error}`);
+    }
+  }
+  const sends = outbox.flush();
+  if (sends.length !== 0) port.postMessage({ kind: 'send', sends });
+}
+
+// Serves the clients over `channel`, the port to the plugin's host, from
+// now on: what comes in is a record per message — `{kind, client, ...}` —
+// held until the returned function starts the ticks, which the host calls
+// once the backend has evaluated, so the first tick delivers what arrived
+// meanwhile, the first join included, to the handlers the module
+// registered. `tick` runs the frame once per tick from then on.
+export function attachClients(channel, { tick = (fn) => setInterval(fn, NET_TICK_MS) } = {}) {
+  port = channel;
+  side.backend = true;
+  if (typeof globalThis.requestAnimationFrame !== 'function') {
+    globalThis.requestAnimationFrame = requestAnimationFrame;
+    globalThis.cancelAnimationFrame = cancelAnimationFrame;
+  }
+  // A backend has no view: its viewport reads zero.
+  globalThis.innerWidth ??= 0;
+  globalThis.innerHeight ??= 0;
+  port.on('message', (records) => inbox.receive(records));
+  return function start() {
+    frame();
+    tick(frame);
+  };
+}

package/src/dev.js

@@ -0,0 +1,122 @@
+// The dev server's model-call route, its stand-in for Dewdrop. It takes
+// the envelope `llm.fetch` posts — the provider URL, method, headers, and
+// body — adds the key from the developer's environment, sends the call,
+// and answers with the provider's status, content type, and body, or a
+// reason in the `x-dew-error` header for a call that got no response, as
+// Dewdrop refuses one. Asked with GET, it names the providers it holds
+// keys for.
+import { LLM_TIMEOUT_MS, MAX_LLM_REQUEST_BYTES, MAX_LLM_RESPONSE_BYTES, PROVIDERS } from './providers.js';
+import { ROUTE_HEADER } from './route.js';
+
+// Headers the transport sets for itself, dropped from the game's request.
+const HOP_HEADERS = ['host', 'content-length', 'transfer-encoding', 'connection', 'expect'];
+
+function readBody(req, limit) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let length = 0;
+    req.on('data', (chunk) => {
+      length += chunk.length;
+      if (length > limit) {
+        reject(new Error(`a call is at most ${MAX_LLM_REQUEST_BYTES} bytes with its headers and body`));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+function refuse(res, status, reason) {
+  res.statusCode = status;
+  res.setHeader('x-dew-error', reason);
+  res.setHeader('content-type', 'text/plain');
+  res.end(reason);
+}
+
+// Where a host's calls go: the provider's own origin, or a test's listener.
+function originFor(origins, host) {
+  return origins[host] ?? `https://${host}`;
+}
+
+// `env` holds the keys by variable name; `fetch` sends the call; `origins`
+// maps a provider host to a stand-in for tests. The returned function is
+// connect middleware, as Vite's server takes it.
+export function createLlmMiddleware({ env = process.env, fetch = globalThis.fetch, origins = {} } = {}) {
+  return async (req, res) => {
+    // Every answer says it came from this route, refusals included.
+    res.setHeader(ROUTE_HEADER, 'llm');
+    // GET names the providers with a key; POST carries a call.
+    if (req.method === 'GET') {
+      const hosts = PROVIDERS.filter((provider) => env[provider.keyVar]).map((provider) => provider.host);
+      res.statusCode = 200;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ hosts }));
+      return;
+    }
+    if (req.method !== 'POST') {
+      refuse(res, 405, 'the model-call route takes GET or POST');
+      return;
+    }
+    let envelope;
+    try {
+      // The envelope carries the body as base64, so the byte budget leaves
+      // room for its expansion and the JSON around it.
+      envelope = JSON.parse((await readBody(req, MAX_LLM_REQUEST_BYTES * 2)).toString('utf8'));
+    } catch (error) {
+      refuse(res, 400, error.message);
+      return;
+    }
+    let url;
+    try {
+      url = new URL(envelope.url);
+    } catch {
+      refuse(res, 400, `${envelope.url} is not a URL`);
+      return;
+    }
+    const provider = url.protocol === 'https:' && !url.port && !url.username && !url.password
+      ? PROVIDERS.find((each) => each.host === url.hostname)
+      : undefined;
+    if (provider === undefined) {
+      refuse(res, 502, `${url.origin} is not a model provider Dewdrop carries calls to`);
+      return;
+    }
+    const key = env[provider.keyVar];
+    if (!key) {
+      refuse(res, 502, `no key for ${provider.host}: set ${provider.keyVar}`);
+      return;
+    }
+    const headers = new Headers();
+    for (const [name, value] of envelope.headers ?? []) {
+      const lower = String(name).toLowerCase();
+      if (HOP_HEADERS.includes(lower) || lower === provider.header) continue;
+      headers.set(lower, String(value));
+    }
+    headers.set(provider.header, provider.prefix + key);
+    const body = Buffer.from(String(envelope.body ?? ''), 'base64');
+    let upstream;
+    try {
+      upstream = await fetch(originFor(origins, provider.host) + url.pathname + url.search, {
+        method: envelope.method,
+        headers,
+        body: body.length > 0 ? body : undefined,
+        redirect: 'manual',
+        signal: AbortSignal.timeout(LLM_TIMEOUT_MS),
+      });
+    } catch (error) {
+      refuse(res, 502, `${provider.host}: ${error.message}`);
+      return;
+    }
+    const answer = Buffer.from(await upstream.arrayBuffer());
+    if (answer.length > MAX_LLM_RESPONSE_BYTES) {
+      refuse(res, 502, `${provider.host}: the response is past ${MAX_LLM_RESPONSE_BYTES} bytes`);
+      return;
+    }
+    res.statusCode = upstream.status;
+    const type = upstream.headers.get('content-type');
+    if (type !== null) res.setHeader('content-type', type);
+    res.end(answer);
+  };
+}

package/src/env.js

@@ -0,0 +1,40 @@
+// The keys the dev route reads: the project's .env files in Vite's order,
+// then the environment, parsed here so the plugin imports nothing from
+// Vite and works linked from a checkout as well as installed.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// The variables in one `.env` file: `KEY=VALUE` lines, `#` comments,
+// optional quotes; nothing expanded.
+export function parseDotenv(text) {
+  const out = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const at = line.indexOf('=');
+    if (at <= 0) continue;
+    const key = line.slice(0, at).trim().replace(/^export\s+/, '');
+    let value = line.slice(at + 1).trim();
+    // A quoted value runs to its closing quote, whatever follows; a bare
+    // one runs to a comment.
+    const quoted = value.match(/^(["'])(.*?)\1/);
+    if (quoted) value = quoted[2];
+    else {
+      const comment = value.indexOf(' #');
+      if (comment >= 0) value = value.slice(0, comment).trim();
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+// The environment the route reads keys from: the project's `.env` files
+// in Vite's order, then the process's own, which wins.
+export function loadKeys(root, mode) {
+  const env = {};
+  for (const name of ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`]) {
+    const path = join(root, name);
+    if (existsSync(path)) Object.assign(env, parseDotenv(readFileSync(path, 'utf8')));
+  }
+  return { ...env, ...process.env };
+}

package/src/index.js

@@ -0,0 +1,29 @@
+// `dewdrop-sdk` on a developer's machine. On Dewdrop, Dewdrop supplies
+// `dewdrop-sdk` itself, so a game written against this runs unchanged there;
+// here each export carries its call through the Vite dev server: `llm`
+// over its route, `backend` over its socket to the backend the plugin
+// runs, and `clients`, in that backend, over its port back.
+export { llm } from './llm.js';
+export { backend } from './backend.js';
+export { clients } from './clients.js';
+import { attachBackend, joining } from './backend.js';
+
+// Where the page's URL joins this tab: `player` is the label it names —
+// on Dewdrop, the player's username — the empty string when it names none
+// and always in a backend's thread, where there is no location.
+const joined = joining(typeof location === 'undefined' ? '' : location.search);
+export const player = joined.player;
+
+// A page served by the dev server joins its room's backend as it loads,
+// told by the plugin whether the game has one; a built game, or one
+// served by something else, has no channel and says so when it sends.
+if (typeof document !== 'undefined' && import.meta.hot) {
+  const meta = document.querySelector('meta[name="dew-backend"]');
+  attachBackend(import.meta.hot, {
+    channel: meta !== null,
+    hasBackend: meta?.content === 'yes',
+    frame: (fn) => requestAnimationFrame(fn),
+    room: joined.room,
+    player: joined.player,
+  });
+}

package/src/llm.js

@@ -0,0 +1,96 @@
+// `llm.fetch` and `llm.providers` on a developer's machine: a model call
+// carried by the Vite dev server's route (see ./vite.js) with the key from
+// the developer's own environment, so a game's code is the same here and
+// on Dewdrop and the key never reaches the browser; and the providers that
+// route holds keys for. The checks and their messages are Dewdrop's, so a
+// call that fails here fails there the same way.
+import { MAX_LLM_HEADERS, MAX_LLM_INFLIGHT, MAX_LLM_REQUEST_BYTES } from './providers.js';
+import { NO_ROUTE, ROUTE_HEADER, routeUrl } from './route.js';
+
+let inflight = 0;
+
+// The bytes a call counts against its cap: its method, URL, headers, and
+// body, plus four bytes for the call and four for each length and count.
+function requestBytes(method, url, headers, bodyLength) {
+  const utf8 = (text) => new TextEncoder().encode(text).length;
+  let size = 4 + 4 + utf8(method) + 4 + utf8(url) + 4;
+  for (const [name, value] of headers) size += 4 + utf8(name) + 4 + utf8(value);
+  return size + 4 + bodyLength;
+}
+
+function base64(bytes) {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += 0x8000) binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(binary);
+}
+
+// The checks a call fails before it is posted are made as it is made, as
+// on Dewdrop, so a fifth call while four are outstanding is refused
+// whether or not the four have posted yet. A call counts as outstanding
+// from its acceptance until the route answers, an aborted one included:
+// aborting rejects the caller at once and drops the answer, but the call
+// itself has gone.
+function fetchModel(input, init) {
+  return new Promise((resolve, reject) => {
+    let request;
+    try { request = new Request(input, init); } catch (error) { reject(error); return; }
+    if (request.signal.aborted) { reject(request.signal.reason); return; }
+    // Only HTTPS leaves the game; whether the host is a provider is the
+    // route's to say, and it refuses a call it will not carry with the
+    // reason.
+    const url = new URL(request.url);
+    if (url.protocol !== 'https:') {
+      reject(new TypeError(`llm.fetch: ${url.origin} is not a model provider Dewdrop carries calls to`));
+      return;
+    }
+    const headers = [...request.headers];
+    if (headers.length > MAX_LLM_HEADERS) {
+      reject(new RangeError(`llm.fetch: a call names at most ${MAX_LLM_HEADERS} headers`));
+      return;
+    }
+    if (inflight >= MAX_LLM_INFLIGHT) {
+      reject(new RangeError(`llm.fetch: at most ${MAX_LLM_INFLIGHT} calls are outstanding at once`));
+      return;
+    }
+    inflight += 1;
+    const onAbort = () => reject(request.signal.reason);
+    request.signal.addEventListener('abort', onAbort, { once: true });
+    carry(request, headers).then(resolve, reject).finally(() => {
+      inflight -= 1;
+      request.signal.removeEventListener('abort', onAbort);
+    });
+  });
+}
+
+// Posts one accepted call to the route and returns its answer.
+async function carry(request, headers) {
+  const body = new Uint8Array(await request.arrayBuffer());
+  if (requestBytes(request.method, request.url, headers, body.length) > MAX_LLM_REQUEST_BYTES) {
+    throw new RangeError(`llm.fetch: a call is at most ${MAX_LLM_REQUEST_BYTES} bytes with its headers and body`);
+  }
+  const response = await globalThis.fetch(routeUrl(), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ url: request.url, method: request.method, headers, body: base64(body) }),
+  });
+  if (!response.headers.has(ROUTE_HEADER)) throw new TypeError(`llm.fetch: ${NO_ROUTE}`);
+  const reason = response.headers.get('x-dew-error');
+  if (reason !== null) throw new TypeError(`llm.fetch: ${reason}`);
+  return response;
+}
+
+// The providers' hosts the dev server holds keys for: asked of its route,
+// once, since the browser cannot read the developer's environment.
+let known = null;
+async function providers() {
+  if (known === null) {
+    const response = await globalThis.fetch(routeUrl());
+    if (!response.headers.has(ROUTE_HEADER)) throw new TypeError(`llm.providers: ${NO_ROUTE}`);
+    const reason = response.headers.get('x-dew-error');
+    if (reason !== null) throw new TypeError(`llm.providers: ${reason}`);
+    known = Object.freeze((await response.json()).hosts.map(String));
+  }
+  return known;
+}
+
+export const llm = Object.freeze({ fetch: fetchModel, providers });

package/src/net.js

@@ -0,0 +1,159 @@
+// The message surface's shared half: the caps, a message measured as
+// Dewdrop measures it, the envelope a frame's sends travel in over the dev
+// server's socket, and the outbox and inbox that hold a game's messages to
+// the caps. The checks and their messages are Dewdrop's, so a send that
+// fails here fails on Dewdrop the same way.
+
+// The limits Dewdrop holds a game to.
+export const MAX_NET_MESSAGE_BYTES = 64 << 10;
+export const MAX_NET_CLIENT_FRAME_BYTES = 16 << 10;
+export const MAX_NET_BACKEND_FRAME_BYTES = 256 << 10;
+export const MAX_NET_INBOX_BYTES = 256 << 10;
+// What each message costs beyond its bytes, toward its frame's cap and
+// the inbox's, an empty message included.
+export const NET_RECORD_HEADER_BYTES = 16;
+// The most bytes a player's label takes: the name the player joined
+// under, which the backend hears on the join.
+export const MAX_NET_PLAYER_BYTES = 64;
+// How often the local backend ticks: sixty times a second.
+export const NET_TICK_MS = 1000 / 60;
+
+// A message's kind and bytes: a string as UTF-8 text, an ArrayBuffer or a
+// view of one as binary; anything else is refused, `op` naming the call.
+export function measure(op, data) {
+  if (typeof data === 'string') return { text: true, bytes: new TextEncoder().encode(data) };
+  if (Object.prototype.toString.call(data) === '[object ArrayBuffer]') return { text: false, bytes: new Uint8Array(data) };
+  if (ArrayBuffer.isView(data)) return { text: false, bytes: new Uint8Array(data.buffer, data.byteOffset, data.byteLength) };
+  throw new TypeError(`${op}: a message is a string, an ArrayBuffer, or a view of one`);
+}
+
+// Bytes as base64, as the dev server's socket carries them.
+function base64(bytes) {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += 0x8000) binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(binary);
+}
+
+function unbase64(text) {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes.buffer;
+}
+
+// One message as the envelope carries it: text as itself, bytes as base64.
+export function pack(op, data) {
+  const { text, bytes } = measure(op, data);
+  return text ? { t: 's', d: data, n: bytes.length } : { t: 'b', d: base64(bytes), n: bytes.length };
+}
+
+// A message out of the envelope: a string, or a fresh ArrayBuffer.
+export function unpack(item) {
+  return item.t === 's' ? item.d : unbase64(item.d);
+}
+
+// A player's or a backend's sends for one frame, held to the message cap
+// and to its `frameCap`, each message costing its bytes plus
+// `NET_RECORD_HEADER_BYTES`: `push` queues one message for the frame,
+// refusing past either cap, and `flush` takes the frame's items and starts
+// the next.
+export function createOutbox(frameCap) {
+  let sent = 0;
+  let items = [];
+  return {
+    push(op, to, data) {
+      const item = pack(op, data);
+      if (item.n > MAX_NET_MESSAGE_BYTES) throw new RangeError(`${op}: a message is at most ${MAX_NET_MESSAGE_BYTES} bytes`);
+      const cost = NET_RECORD_HEADER_BYTES + item.n;
+      if (sent + cost > frameCap) throw new RangeError(`${op}: a frame sends at most ${frameCap} bytes`);
+      sent += cost;
+      items.push({ to, ...item });
+    },
+    flush() {
+      const frame = items;
+      items = [];
+      sent = 0;
+      return frame;
+    },
+  };
+}
+
+// A receiver's inbox, held to its cap: `receive` keeps the records handed
+// over — messages, and for a backend joins and leaves — and past the cap
+// drops every message not yet drained for one gap, joins and leaves kept;
+// `drain` takes what is held, in order.
+export function createInbox() {
+  let held = [];
+  let bytes = 0;
+  const size = (record) => NET_RECORD_HEADER_BYTES + (record.n ?? 0);
+  return {
+    receive(records) {
+      for (const record of records) {
+        const needed = size(record);
+        if (record.kind === 'message' && bytes + needed > MAX_NET_INBOX_BYTES) {
+          held = held.filter((each) => each.kind === 'join' || each.kind === 'leave');
+          held.push({ kind: 'gap' });
+          bytes = held.reduce((sum, each) => sum + size(each), 0);
+          continue;
+        }
+        held.push(record);
+        bytes += needed;
+      }
+    },
+    drain() {
+      const records = held;
+      held = [];
+      bytes = 0;
+      return records;
+    },
+  };
+}
+
+// A player's label held to its cap: text cut at the cap on a character
+// boundary, since a cut through a character would name no one; anything
+// but a string is the empty label.
+export function label(text) {
+  if (typeof text !== 'string') return '';
+  const { read } = new TextEncoder().encodeInto(text, new Uint8Array(MAX_NET_PLAYER_BYTES));
+  return text.slice(0, read);
+}
+
+// Whether this is the backend's thread, which `attachClients` says: the
+// client's surface is unavailable there, as on Dewdrop.
+export const side = { backend: false };
+
+// The `on<event>` handler properties of an EventTarget, as a browser
+// defines them: set to a function, it listens; set to anything else, it
+// stops.
+export function defineHandlers(proto, types) {
+  const bound = new WeakMap();
+  for (const type of types) {
+    Object.defineProperty(proto, `on${type}`, {
+      configurable: true,
+      enumerable: true,
+      get() { return bound.get(this)?.[type]?.fn ?? null; },
+      set(fn) {
+        const mine = bound.get(this) ?? {};
+        bound.set(this, mine);
+        if (mine[type]) this.removeEventListener(type, mine[type].listener);
+        delete mine[type];
+        if (typeof fn !== 'function') return;
+        const listener = (event) => fn.call(this, event);
+        mine[type] = { fn, listener };
+        this.addEventListener(type, listener);
+      },
+    });
+  }
+}
+
+// An event about one client, as a backend hears them: a message event, as
+// on Dewdrop, with `client` the number the backend knows the client by,
+// `data` the message when there is one, and on a join `player`, the label
+// the client joined under.
+export class ClientEvent extends MessageEvent {
+  constructor(type, { client, data = null, player } = {}) {
+    super(type, { data });
+    this.client = client;
+    if (player !== undefined) this.player = player;
+  }
+}

package/src/providers.js

@@ -0,0 +1,20 @@
+// The providers Dewdrop carries a game's model calls to, each with the
+// variable the dev server reads its key from and the header that carries
+// the key, and the limits Dewdrop holds a call to.
+
+export const PROVIDERS = [
+  { host: 'api.openai.com', keyVar: 'OPENAI_API_KEY', header: 'authorization', prefix: 'Bearer ' },
+  { host: 'api.anthropic.com', keyVar: 'ANTHROPIC_API_KEY', header: 'x-api-key', prefix: '' },
+  { host: 'generativelanguage.googleapis.com', keyVar: 'GEMINI_API_KEY', header: 'x-goog-api-key', prefix: '' },
+];
+
+// The most bytes one call carries with its method, URL, headers, and body.
+export const MAX_LLM_REQUEST_BYTES = 64 << 10;
+// The most headers one call names.
+export const MAX_LLM_HEADERS = 16;
+// The most bytes of a provider's response body; a longer one fails whole.
+export const MAX_LLM_RESPONSE_BYTES = 32 << 10;
+// The most calls a game has outstanding at once.
+export const MAX_LLM_INFLIGHT = 4;
+// How long a call may take from sending to its last byte.
+export const LLM_TIMEOUT_MS = 60_000;

package/src/route.js

@@ -0,0 +1,30 @@
+// The contract between the package's two halves: the dev server route
+// `llm` calls, how its answers are told apart from a page served without
+// it, and where a backend finds the dev server from its thread.
+
+// The dev server route the local `llm.fetch` posts to, and the header
+// every answer from it carries, so a page served without the route — a
+// dev server missing the plugin, a static host — is told apart from a
+// provider's own 404.
+export const DEV_ROUTE = '/__dew/llm';
+export const ROUTE_HEADER = 'x-dew-route';
+export const NO_ROUTE = `no model-call route at ${DEV_ROUTE}: add the dew() plugin to vite.config.js, or run the game on Dewdrop`;
+
+import { side } from './net.js';
+
+// Where `llm.fetch` posts from where it runs: the page's own origin in a
+// browser, and from the backend's thread the dev server's, which the
+// plugin's host tells it; a host that could not learn it — a dev server
+// in middleware mode with no `server.origin` — is said so.
+export function routeUrl() {
+  if (typeof window !== 'undefined') return DEV_ROUTE;
+  const origin = process.env.DEW_DEV_ORIGIN ?? '';
+  if (side.backend && origin === '') {
+    throw new TypeError("the dev server's address is unknown to the backend: set server.origin in vite.config.js");
+  }
+  return origin + DEV_ROUTE;
+}
+
+// The message a client sends without a channel to its backend: a page
+// served without the plugin, or a build served by a static host.
+export const NO_CHANNEL = 'no backend channel: add the dew() plugin to vite.config.js, or run the game on Dewdrop';

package/src/serve.js

@@ -0,0 +1,166 @@
+// The dev server's backend host, its stand-in for Dewdrop. A thread runs
+// the project's backend.js for each room the tabs join, from the room's
+// first tab's join to its last tab's leave, the tabs numbered from one per
+// room; each tab's frame of sends reaches its room's thread over the port
+// with the tab's number, and each of the thread's sends reaches the tab it
+// names, or every tab of the room, over the socket. An edit to the backend
+// restarts every room and reloads the tabs, which join afresh. A backend
+// that throws or ends on its own is stopped and the reason logged, and its
+// room stays stopped until the next edit: restarting it would only throw
+// again, and reloading the tabs at each throw would leave nothing to read
+// the error in.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { Worker } from 'node:worker_threads';
+import { label } from './net.js';
+
+// The files an edit to which restarts the backend: the entry and what it
+// reaches through static relative imports.
+export function backendFiles(entry) {
+  const files = new Set();
+  const visit = (file) => {
+    if (files.has(file) || !existsSync(file)) return;
+    files.add(file);
+    const text = readFileSync(file, 'utf8');
+    for (const match of text.matchAll(/^\s*(?:import|export)\b[^;'"]*?from\s+['"](\.\.?\/[^'"]+)['"]/gm)) {
+      visit(resolve(dirname(file), match[1]));
+    }
+  };
+  visit(entry);
+  return files;
+}
+
+// Runs the backends at `entry` for the tabs that join over `ws`, the dev
+// server's socket, one per room; `watcher` reports edits, `origin` is the
+// dev server's address for a backend's model calls, and `log` hears why a
+// backend ended.
+export function createBackendHost({ entry, ws, watcher, origin = () => '', log = console }) {
+  // Read afresh at each start, so a file the backend imports since is watched too.
+  let files = backendFiles(entry);
+  // Each room's backend by the room's key, and each joined tab's room.
+  const rooms = new Map();
+  const tabs = new Map();
+
+  // One room's backend: its thread from the room's first tab's join to
+  // its last tab's leave, its tabs by number from one.
+  function createRoom(key) {
+    const name = key === '' ? 'the backend' : `the backend of room ${JSON.stringify(key)}`;
+    const members = new Map();
+    let worker = null;
+    let next = 1;
+    let broken = false;
+
+    function deliver(sends) {
+      for (const [client, number] of members) {
+        const items = sends.filter((send) => send.to === 0 || send.to === number);
+        if (items.length !== 0) client.send('dew:recv', { items });
+      }
+    }
+
+    function start() {
+      files = backendFiles(entry);
+      worker = new Worker(new URL('./backend-host.js', import.meta.url), { workerData: { entry, origin: origin() } });
+      const started = worker;
+      started.on('message', (message) => {
+        if (message.kind === 'send' && worker === started) deliver(message.sends);
+      });
+      started.on('error', (error) => {
+        if (worker === started) broke(`${name} threw: ${error.stack ?? error}`);
+      });
+      started.on('exit', (code) => {
+        if (worker === started) broke(`${name} ended with ${code}`);
+      });
+    }
+
+    // Ends the thread and forgets every tab, which join afresh next time.
+    function stop() {
+      const ended = worker;
+      worker = null;
+      for (const client of members.keys()) tabs.delete(client);
+      members.clear();
+      next = 1;
+      if (ended !== null) ended.terminate();
+    }
+
+    // A thread that threw or ended: stopped, said so, and not started
+    // again for a join until an edit lands.
+    function broke(reason) {
+      log.error(`[dewdrop] ${reason}; ${name} is stopped until it is edited`);
+      stop();
+      broken = true;
+    }
+
+    const room = {
+      join(client, player) {
+        if (broken) return;
+        const number = next++;
+        members.set(client, number);
+        tabs.set(client, room);
+        if (worker === null) start();
+        worker.postMessage([{ kind: 'join', client: number, player }]);
+        client.socket.once('close', () => host.leave(client));
+      },
+      leave(client) {
+        const number = members.get(client);
+        if (number === undefined) return;
+        members.delete(client);
+        tabs.delete(client);
+        if (members.size === 0) {
+          stop();
+          rooms.delete(key);
+          return;
+        }
+        worker.postMessage([{ kind: 'leave', client: number }]);
+      },
+      receive(client, items) {
+        const number = members.get(client);
+        if (number === undefined || worker === null) return;
+        worker.postMessage(items.map((item) => ({ kind: 'message', client: number, ...item })));
+      },
+      stop,
+    };
+    return room;
+  }
+
+  // Ends every room's thread and forgets every tab.
+  function close() {
+    for (const room of rooms.values()) room.stop();
+    rooms.clear();
+  }
+
+  // An edit: every room's backend ends and the tabs reload, joining
+  // fresh ones.
+  function restart(reason) {
+    log.error(`[dewdrop] ${reason}; restarting the backend`);
+    close();
+    ws.send({ type: 'full-reload', path: '*' });
+  }
+
+  const host = {
+    // A tab joins the room its page named under the name it gave; a page
+    // that named neither joins the empty room unnamed.
+    join(client, { room = '', player = '' } = {}) {
+      if (tabs.has(client)) return;
+      const key = typeof room === 'string' ? room : '';
+      let it = rooms.get(key);
+      if (it === undefined) {
+        it = createRoom(key);
+        rooms.set(key, it);
+      }
+      it.join(client, label(player));
+    },
+    leave(client) {
+      tabs.get(client)?.leave(client);
+    },
+    receive(client, items) {
+      tabs.get(client)?.receive(client, items);
+    },
+    close,
+  };
+  ws.on('dew:join', (data, client) => host.join(client, { room: data?.room, player: data?.player }));
+  ws.on('dew:send', (data, client) => host.receive(client, data.items ?? []));
+  watcher.on('change', (file) => {
+    if (files.has(resolve(file))) restart(`${file} changed`);
+  });
+  return host;
+}

package/src/vite.js

@@ -0,0 +1,131 @@
+// The Vite plugin. For a Dewdrop build, `vite build --mode dew`: three and
+// the SDK left as imports for Dewdrop to supply, one chunk of ES modules
+// with dynamic imports folded in, written as `main.js` at the top of the
+// output, no module preload, a root base, the files Vite emits under
+// `ui/`, and the built page opened in the document by the entry; a game
+// 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, and the host that runs the game's backend for
+// the tabs that join it. 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 } from 'node:fs';
+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 { DEV_ROUTE } from './route.js';
+import { createBackendHost } from './serve.js';
+
+// The imports Dewdrop supplies, left in the output: three and the paths
+// into it, and the SDK by its name. Dewdrop supplies nothing else, a path
+// into the SDK included, so the build takes every other import in.
+export function isRuntimeModule(id) {
+  return id === 'three' || id.startsWith('three/') || id === 'dewdrop-sdk';
+}
+
+export const DEW_MODE = 'dew';
+
+// Where a project's backend is: `backend.js` at the root, else
+// `src/backend.js`, else none.
+export function backendEntry(root) {
+  for (const name of [BACKEND_FILE, `src/${BACKEND_FILE}`]) {
+    const file = resolve(root, name);
+    if (existsSync(file)) return file;
+  }
+  return null;
+}
+
+export default function dew() {
+  let dewBuild = false;
+  let serving = false;
+  let entry = null;
+  return {
+    name: 'dew',
+    config(userConfig, env) {
+      const root = userConfig.root ?? process.cwd();
+      entry = backendEntry(root);
+      dewBuild = env.mode === DEW_MODE;
+      serving = env.command === 'serve';
+      if (!dewBuild) {
+        // Served as source, so the hot context the client's `backend`
+        // joins over is injected as in the game's own modules.
+        return env.command === 'serve' ? { optimizeDeps: { exclude: ['dewdrop-sdk'] } } : undefined;
+      }
+      const major = detectViteMajor(root);
+      const config = {
+        base: '/',
+        build: {
+          modulePreload: false,
+          assetsDir: ASSETS_DIR,
+          rollupOptions: {
+            external: isRuntimeModule,
+            output: outputOptions(major),
+          },
+        },
+      };
+      if (entry === null) return config;
+      // The backend is a second build of its own, since one chunk with its
+      // dynamic imports folded in is one input: an environment beside the
+      // client's, built after it into the same output, on the app builder
+      // Vite 6 brought.
+      if (major === undefined) throw new Error('a backend build needs Vite 6 or later, and no Vite was found under node_modules');
+      if (major < 6) throw new Error('a backend build needs Vite 6 or later');
+      config.environments = {
+        backend: {
+          build: {
+            emptyOutDir: false,
+            copyPublicDir: false,
+            rollupOptions: {
+              input: entry,
+              output: outputOptions(major, BACKEND_FILE),
+            },
+          },
+        },
+      };
+      config.builder = {
+        async buildApp(builder) {
+          await builder.build(builder.environments.client);
+          await builder.build(builder.environments.backend);
+        },
+      };
+      return config;
+    },
+    // The built page, its URLs rewritten and its stylesheets linked as Vite
+    // made it for a browser, is opened at the top of the entry. Last of the
+    // hooks, since Vite emits the page in its own generateBundle.
+    generateBundle: {
+      order: 'post',
+      handler(_options, bundle) {
+        if (!dewBuild) return;
+        const chunk = bundle[ENTRY_FILE];
+        if (chunk === undefined || chunk.type !== 'chunk') return;
+        const page = bundle[PAGE_FILE];
+        if (page?.type !== 'asset') return;
+        const html = page.source instanceof Uint8Array ? new TextDecoder().decode(page.source) : String(page.source);
+        chunk.code = openPage(html) + chunk.code;
+      },
+    },
+    // The page the dev server serves is told whether the game has a
+    // backend, which the client's `backend` reads before it joins; a
+    // build's page, which no dev server serves, is left alone.
+    transformIndexHtml() {
+      if (!serving) return undefined;
+      return [{ tag: 'meta', attrs: { name: 'dew-backend', content: entry === null ? 'no' : 'yes' }, injectTo: 'head' }];
+    },
+    configureServer(server) {
+      // The keys come from the project's own .env files and the
+      // environment, every variable rather than the VITE_-prefixed ones a
+      // page may see.
+      const env = loadKeys(server.config.envDir ?? server.config.root, server.config.mode);
+      server.middlewares.use(DEV_ROUTE, createLlmMiddleware({ env }));
+      if (entry === null) return;
+      createBackendHost({
+        entry,
+        ws: server.ws,
+        watcher: server.watcher,
+        origin: () => server.resolvedUrls?.local?.[0]?.replace(/\/$/, '') ?? server.config.server?.origin ?? '',
+      });
+    },
+  };
+}