@aethervtt/shard-protocol 0.0.1 → 0.2.0

package/dist/ablate.d.ts

@@ -0,0 +1,2 @@
+import type { MethodDef } from './server.js';
+export declare const ABLATE_METHODS: MethodDef[];

package/dist/ablate.js

@@ -0,0 +1,62 @@
+import { defineSchema, Last, PostUpdate, t } from "@aethervtt/shard-core";
+import { ablatePasses, Gpu, Graph, Views } from "@aethervtt/shard-render";
+import { AppControlResource } from "@aethervtt/shard-runtime";
+function renderOnly(app) {
+  app.runSchedule(PostUpdate);
+  app.runSchedule(Last);
+}
+function nextFrame(app) {
+  return new Promise((resolve) => {
+    const off = app.onFrame(() => {
+      off();
+      resolve();
+    });
+  });
+}
+const ABLATE_METHODS = [
+  {
+    name: "perf.ablate",
+    description: "Each render-graph pass's GPU cost, measured honestly on any GPU: rounds alternate the pass disabled and enabled, and its cost is the median drop in gpu:frame (first pass start to last pass end). Use it where per-pass timestamps overlap (tile-based GPUs such as Apple's, where pass times add up to more than the frame). A disabled pass still begins and ends, so what reads its textures stays valid; the image is wrong while it runs. Needs timestamp-query. It runs (passes + 2) \xD7 rounds \xD7 (frames + 4) frames: three passes at the defaults take about 50 s at 60 fps.",
+    params: defineSchema("protocol/AblateParams", {
+      passes: t.list(t.string, {
+        description: "Render-graph nodes to measure (render.describe lists them). Default: every node the last frame ran."
+      }),
+      frames: t.u32({ default: 120, min: 1, max: 1e4, description: "Frames per measurement." }),
+      rounds: t.u32({ default: 5, min: 1, max: 100, description: "Interleaved rounds." }),
+      together: t.bool({ description: "Also measure every pass disabled at once." })
+    }),
+    handler: async ({ app, world, options }, p) => {
+      const manual = (options.frames ?? "manual") === "manual" || world.resource(AppControlResource).paused;
+      const frame = () => manual ? renderOnly(app) : nextFrame(app);
+      const graph = world.resource(Graph);
+      const gpu = world.resource(Gpu);
+      for (let i = 0; i < 20; i++) {
+        await frame();
+        await gpu.pipelines.whenIdle();
+        if (i > 0 && gpu.pipelines.pending === 0 && gpu.pipelines.skipped === 0) break;
+      }
+      let passes = p.passes ?? [];
+      if (passes.length === 0) {
+        const ran = /* @__PURE__ */ new Set();
+        const perView = graph.describe().perView;
+        for (const view of world.resource(Views).list) {
+          for (const name of perView[view.name]?.order ?? []) ran.add(name);
+        }
+        passes = [...ran];
+      }
+      return ablatePasses(
+        world,
+        {
+          passes,
+          frames: p.frames,
+          rounds: p.rounds,
+          together: p.together
+        },
+        frame
+      );
+    }
+  }
+];
+export {
+  ABLATE_METHODS
+};

package/dist/budgets.d.ts

@@ -0,0 +1,2 @@
+import type { MethodDef } from './server.js';
+export declare const BUDGET_METHODS: MethodDef[];

package/dist/budgets.js

@@ -0,0 +1,20 @@
+import { defineSchema, t } from "@aethervtt/shard-core";
+import { describeBudgets } from "@aethervtt/shard-runtime";
+const BUDGET_METHODS = [
+  {
+    name: "perf.budgets",
+    description: "Performance budgets (0075, bench/perf/budgets.json) for this app: the named machine it runs on (detected from the CPU model where the host exposes it, and the GPU adapter; null with a perf/unknown-machine warning when it can't tell, and then numbers are the closest machine's), every budget resolved for it with the profiler's latest p95 against it, over budget first; and the scenario's slices (the app's App.perfScenario, or `scenario`): each slice's measured share of the frame (from the profiler's aggregates, gpu:frame for GPU slices, frame for CPU) next to its budget share, over first. Hosts supply the files: the CLI loads them from the repo or project, shard dev serves them to its page.",
+    params: defineSchema("protocol/BudgetsParams", {
+      scenario: t.string({
+        description: "A scenario of budgets.json to measure (scatter-walk, crowd, planet-descent, tabletop-max). Default: the app's own (App.perfScenario)."
+      })
+    }),
+    handler: ({ world }, p) => {
+      const scenario = p.scenario;
+      return describeBudgets(world, { scenario: scenario ? scenario : void 0 });
+    }
+  }
+];
+export {
+  BUDGET_METHODS
+};

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { ABLATE_METHODS } from './ablate.js';
+export { BUDGET_METHODS } from './budgets.js';
 export { decodePng, encodePng, toBase64 } from './png.js';
 export { type PreviewImage, previewAsset, previewKtx2 } from './preview.js';
 export { createProtocolServer, type HandlerContext, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, METHODS, type MethodDef, type ProtocolServer, type ProtocolServerOptions, type Topic, } from './server.js';

package/dist/index.js

@@ -1,3 +1,5 @@
+import { ABLATE_METHODS } from "./ablate.js";
+import { BUDGET_METHODS } from "./budgets.js";
 import { decodePng, encodePng, toBase64 } from "./png.js";
 import { previewAsset, previewKtx2 } from "./preview.js";
 import {
@@ -6,6 +8,8 @@ import {
 } from "./server.js";
 import { connectToHub, DEFAULT_HUB_PORT } from "./transport.js";
 export {
+  ABLATE_METHODS,
+  BUDGET_METHODS,
   DEFAULT_HUB_PORT,
   METHODS,
   connectToHub,

package/dist/preview.js

@@ -191,6 +191,7 @@ async function renderPreview(world, path, type, width, height) {
     return { width: image.width, height: image.height, data: image.data };
   } finally {
     releaseSceneHooks(app.world);
+    await app.dispose();
     target.destroy();
   }
 }

package/dist/server.d.ts

@@ -43,6 +43,12 @@ export interface ProtocolServerOptions {
     platform?: Platform;
     /** Extra methods from the host (e.g. `project.reload`), added to the built-in ones. */
     methods?: readonly MethodDef[];
+    /**
+     * The only methods this server answers (0061): everything else, `subscribe` included, fails with
+     * `protocol/method-not-allowed`. A host that forwards requests from hosted mods passes the few
+     * it allows; omit it for agents and tools, which get every method.
+     */
+    allow?: readonly string[];
 }
 export declare const METHODS: MethodDef[];
 export type Topic = 'log' | 'error' | 'frame' | 'project';

package/dist/server.js

@@ -9,12 +9,14 @@ import {
   isPlainObject,
   Last,
   PostUpdate,
+  ProfilerResource,
   ShardError,
   t
 } from "@aethervtt/shard-core";
 import {
   describeInput,
   injectInput,
+  simulateGestures,
   startRecording,
   startReplay,
   stopRecording
@@ -41,6 +43,8 @@ import {
 } from "@aethervtt/shard-render";
 import {
   AppControlResource,
+  capturePerf,
+  describePerf,
   LogResource,
   Time
 } from "@aethervtt/shard-runtime";
@@ -73,6 +77,8 @@ import {
   Transform,
   worldPosition64
 } from "@aethervtt/shard-transform";
+import { ABLATE_METHODS } from "./ablate.js";
+import { BUDGET_METHODS } from "./budgets.js";
 import { encodePng, toBase64 } from "./png.js";
 const CAPTURE_DEBUG_VIEWS = ["clusters", "cascades", "lod", "culling", "none"];
 import { previewAsset } from "./preview.js";
@@ -87,7 +93,7 @@ function resolveEntity(world, ref) {
     hint: 'Pass an entity id from world.query, or a scene path like "ship/camera".'
   });
 }
-function requireComponent(name) {
+function knownComponent(name) {
   const def = findComponent(name);
   if (!def) {
     throw new ShardError("protocol/unknown-component", `Unknown component "${name}"`, {
@@ -96,6 +102,28 @@ function requireComponent(name) {
   }
   return def;
 }
+function requireOwner(world, name) {
+  const owner = world.owners.find(name);
+  if (!owner) {
+    throw new ShardError("protocol/unknown-owner", `No live owner "${name}"`, {
+      hint: "owners.describe with no name lists every live owner."
+    });
+  }
+  return owner;
+}
+function requireComponent(name) {
+  const def = knownComponent(name);
+  if (def.hostOnly) {
+    throw new ShardError(
+      "core/owner-not-authorable",
+      `"${name}" can't be written through the protocol`,
+      {
+        hint: "Ownership comes from host code holding an Owner (world.owners)."
+      }
+    );
+  }
+  return def;
+}
 function toJson(value) {
   const seen = /* @__PURE__ */ new WeakSet();
   return JSON.parse(
@@ -346,7 +374,7 @@ const METHODS = [
     params: s("SchemaGetParams", {
       name: t.string({ required: true, description: 'Component name, e.g. "render/Camera3d".' })
     }),
-    handler: (_, p) => requireComponent(p.name).jsonSchema()
+    handler: (_, p) => knownComponent(p.name).jsonSchema()
   },
   {
     name: "world.stats",
@@ -439,6 +467,23 @@ const METHODS = [
       return entityJson(world, entity);
     }
   },
+  {
+    name: "owners.describe",
+    description: "Owners (0061). With a name: its usage (entities, triangles, textures, bytes), limits, child owners, asset leases and GPU objects. Without: every live owner.",
+    params: s("OwnersDescribeParams", { name: t.string() }),
+    handler: ({ world }, p) => p.name ? world.owners.describe(requireOwner(world, p.name)) : { owners: world.owners.list() }
+  },
+  {
+    name: "owners.release",
+    description: "Releases an owner and its child owners: despawns their entities, drops their asset leases (unloading assets nobody else leases, with their GPU objects).",
+    params: s("OwnersReleaseParams", { name: t.string({ required: true }) }),
+    handler: ({ world }, p) => {
+      const owner = requireOwner(world, p.name);
+      const entities = world.owners.describe(owner).usage.entities;
+      world.owners.release(owner);
+      return { released: owner.name, entities };
+    }
+  },
   {
     name: "entity.despawn",
     description: "Despawns an entity (and its children unless recursive is false).",
@@ -467,10 +512,19 @@ const METHODS = [
   },
   {
     name: "resource.set",
-    description: "Merges fields into a plain-object resource (e.g. render/AmbientLight).",
+    description: "Merges fields into a plain-object resource (e.g. render/AmbientLight), marking it changed and waking an on-demand app.",
     params: s("ResourceSetParams", { name: t.string({ required: true }), value: t.json() }),
     handler: ({ world }, p) => {
       const def = findResource(p.name);
+      if (def?.hostOnly) {
+        throw new ShardError(
+          "core/owner-not-authorable",
+          `Resource "${p.name}" is written by the host only`,
+          {
+            hint: "Host code sets it; the protocol can read it with resource.get."
+          }
+        );
+      }
       const current = def && world.tryResource(def);
       if (!def || !isPlainObject(current)) {
         throw new ShardError(
@@ -485,7 +539,7 @@ const METHODS = [
         throw new ShardError("schema/type-mismatch", '"value" must be an object', {
           path: "/value"
         });
-      Object.assign(current, p.value);
+      world.patchResource(def, p.value);
       return toJson(current);
     }
   },
@@ -502,10 +556,11 @@ const METHODS = [
     name: "time.resume",
     description: "Resumes a paused game.",
     params: none,
-    handler: ({ world }) => {
+    handler: ({ app, world }) => {
       const control = world.resource(AppControlResource);
       control.paused = false;
       control.pausedByError = false;
+      app.requestFrame();
       return { paused: false, frame: world.resource(Time).frame };
     }
   },
@@ -549,7 +604,7 @@ const METHODS = [
         description: "Limit overlays to entities with all these components."
       }),
       buffer: t.string({
-        description: "Raw floats of a render buffer instead of the display image: 'hdr' (luminance in cd/m\xB2, before post-processing and tonemapping), 'post-hdr' (after the HDR effects, pre-exposed), 'depth', 'velocity' (screen motion in uv units, TAA and motion blur), 'ssao' (ambient occlusion), 'bloom' (the glow's first level), 'dof-half' (color and signed CoC in pixels), or another graph texture. Returned as base64 little-endian rgba32float."
+        description: "Raw floats of a render buffer instead of the display image: 'hdr' (luminance in cd/m\xB2, before post-processing and tonemapping), 'post-hdr' (after the HDR effects, pre-exposed; bloom's glow is added by the tonemap, so it's not in it), 'depth', 'velocity' (screen motion in uv units, TAA and motion blur), 'ssao' (ambient occlusion and view depth, at half resolution), 'bloom' (the glow's first level), 'dof-half' (color and signed CoC in pixels), or another graph texture. Returned as base64 little-endian rgba32float."
       })
     }),
     handler: async ({ app, world, options }, p) => {
@@ -732,6 +787,20 @@ const METHODS = [
       return { queued: true };
     }
   },
+  {
+    name: "input.simulate",
+    description: "Plays pointer gestures a step per frame, in CSS pixels, so controls and drags run headless (0060): [{ drag: { from: [x, y], to: [x, y], button, pointer, modifiers, frames, cancel } }, { pinch: { center, from, to, twist, pan, frames } }, { wheel: { at, dy, dx, modifiers } }, { tap: [x, y] }, { wait: frames }]. Needs gesturesPlugin. Returns how many frames they take.",
+    params: s("SimulateParams", {
+      gestures: t.json({ required: true, description: "The gestures, played one after another." })
+    }),
+    handler: ({ world }, p) => {
+      if (!Array.isArray(p.gestures))
+        throw new ShardError("protocol/invalid-params", "gestures must be a list", {
+          path: "/gestures"
+        });
+      return { frames: simulateGestures(world, p.gestures) };
+    }
+  },
   {
     name: "input.record",
     description: "Starts recording input, or stops and returns the recording.",
@@ -974,6 +1043,87 @@ const METHODS = [
       };
     }
   },
+  {
+    name: "perf.describe",
+    description: 'Profiler aggregates (0074) over the last 120 runs of each span (last, avg, p95, max ms): the frame, each schedule and its command application, systems and other main-thread spans, GPU passes and the GPU frame ("unavailable" without timestamp queries), worker jobs, async spans; memory (GPU ledger by category, JS heap, ECS tables); and the clock (resolution, isolated, timings under four steps are "coarse").',
+    params: s("PerfDescribeParams", {
+      spans: t.list(t.string, {
+        description: 'Only spans these keys cover: a key covers a span it equals or prefixes up to a "/" ("render" covers "render/opaque").'
+      }),
+      top: t.u32({ default: 30, min: 1, max: 1e3, description: "Most spans listed per track." })
+    }),
+    handler: ({ world }, p) => {
+      const spans = p.spans;
+      return toJson(
+        describePerf(world, {
+          spans: spans && spans.length > 0 ? spans : void 0,
+          top: p.top
+        })
+      );
+    }
+  },
+  {
+    name: "perf.capture",
+    description: 'Captures a span timeline (0074) over the next `frames` frames, or with `until.frameMs` a flight recorder that keeps `before` frames and stops `after` frames past the first frame over it. Returns a summary: frame CPU/GPU/interval p50/p95/max, the top spans, and the 5 worst frames, each with the spans most above their median ("over"): the lead for a hitch. The Chrome trace (Perfetto, chrome://tracing) goes to .shard/captures/ (tracePath) where the host can write, else inline (trace).',
+    params: s("PerfCaptureParams", {
+      frames: t.u32({ min: 0, max: 1e5, description: "Frames to capture (default 300)." }),
+      until: t.struct({
+        frameMs: t.f32({
+          min: 0,
+          description: "Flight recorder: stop after the first frame whose CPU time is over this."
+        })
+      }),
+      before: t.u32({
+        default: 120,
+        max: 1e5,
+        description: "Flight recorder: frames kept before."
+      }),
+      after: t.u32({ default: 30, max: 1e5, description: "Flight recorder: frames after." }),
+      timeout: t.f32({
+        default: 60,
+        min: 0,
+        description: "Flight recorder: seconds to wait for a slow frame."
+      }),
+      sample: t.bool({
+        description: "Also sample JavaScript (V8's profiler in Node, JS Self-Profiling in browsers): the hottest functions join the summary."
+      }),
+      devtools: t.bool({
+        description: "Also show spans in Chrome's Performance panel (performance.measure)."
+      }),
+      write: t.bool({ default: true, description: "Write the trace file when the host can." })
+    }),
+    handler: async ({ app, world, options }, p) => {
+      const frameMs = p.until?.frameMs ?? 0;
+      const manual = (options.frames ?? "manual") === "manual";
+      const gpu = world.tryResource(Gpu) !== void 0;
+      return toJson(
+        await capturePerf(world, {
+          frames: p.frames || 300,
+          until: frameMs > 0 ? { frameMs } : void 0,
+          before: p.before,
+          after: p.after,
+          timeout: p.timeout,
+          sample: p.sample,
+          devtools: p.devtools,
+          write: p.write,
+          // Headless: run the frames here, letting GPU readbacks land between them.
+          step: manual ? async () => {
+            app.update(1 / app.fixedHz);
+            if (gpu) await new Promise((resolve) => setTimeout(resolve, 0));
+          } : void 0
+        })
+      );
+    }
+  },
+  {
+    name: "perf.reset",
+    description: "Clears the profiler's aggregates: perf.describe starts over.",
+    params: none,
+    handler: ({ world }) => {
+      world.resource(ProfilerResource).reset();
+      return null;
+    }
+  },
   {
     name: "log.tail",
     description: "Recent log entries (errors from systems, the GPU, and shaders land here).",
@@ -988,7 +1138,9 @@ const METHODS = [
     description: "Recent errors with code, path, and hint.",
     params: s("ErrorsParams", { count: t.u32({ default: 20, min: 1 }) }),
     handler: ({ world }, p) => world.resource(LogResource).errors(p.count)
-  }
+  },
+  ...ABLATE_METHODS,
+  ...BUDGET_METHODS
 ];
 function createProtocolServer(app, options = {}) {
   const ctx = { app, world: app.world, options };
@@ -1021,10 +1173,12 @@ function createProtocolServer(app, options = {}) {
     }
   };
   byName.set(subscribe.name, subscribe);
-  const lookup = (name) => byName.get(name) ?? app.methods.find((m) => m.name === name);
-  return {
+  const allow = options.allow ? new Set(options.allow) : void 0;
+  const lookup = (name) => allow && !allow.has(name) ? void 0 : byName.get(name) ?? app.methods.find((m) => m.name === name);
+  const allowed = (m) => !allow || allow.has(m.name);
+  const server = {
     get methods() {
-      return [...byName.values(), ...app.methods.filter((m) => !byName.has(m.name))];
+      return [...byName.values(), ...app.methods.filter((m) => !byName.has(m.name))].filter(allowed);
     },
     async handle(request) {
       const id = request.id ?? null;
@@ -1033,13 +1187,21 @@ function createProtocolServer(app, options = {}) {
       if (request?.jsonrpc !== "2.0" || typeof request.method !== "string") {
         return reply({ error: { code: ERROR.invalid, message: "Invalid JSON-RPC request" } });
       }
+      if (allow && !allow.has(request.method)) {
+        const err = new ShardError(
+          "protocol/method-not-allowed",
+          `"${request.method}" isn't allowed on this server`,
+          { hint: `This host allows: ${[...allow].join(", ")}.` }
+        );
+        return reply({ error: { code: ERROR.shard, message: err.message, data: err.toJSON() } });
+      }
       const method = lookup(request.method);
       if (!method) {
         return reply({
           error: {
             code: ERROR.notFound,
             message: `Unknown method "${request.method}"`,
-            data: { methods: [...byName.keys(), ...app.methods.map((m) => m.name)] }
+            data: { methods: server.methods.map((m) => m.name) }
           }
         });
       }
@@ -1079,6 +1241,7 @@ function createProtocolServer(app, options = {}) {
       listeners.clear();
     }
   };
+  return server;
 }
 export {
   METHODS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aethervtt/shard-protocol",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -16,16 +16,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@aethervtt/shard-assets": "0.0.1",
-    "@aethervtt/shard-core": "0.0.1",
-    "@aethervtt/shard-input": "0.0.1",
-    "@aethervtt/shard-platform": "0.0.1",
-    "@aethervtt/shard-render": "0.0.1",
-    "@aethervtt/shard-runtime": "0.0.1",
-    "@aethervtt/shard-scene": "0.0.1",
-    "@aethervtt/shard-text": "0.0.1",
-    "@aethervtt/shard-texture": "0.0.1",
-    "@aethervtt/shard-transform": "0.0.1"
+    "@aethervtt/shard-assets": "0.2.0",
+    "@aethervtt/shard-core": "0.2.0",
+    "@aethervtt/shard-input": "0.2.0",
+    "@aethervtt/shard-platform": "0.2.0",
+    "@aethervtt/shard-render": "0.2.0",
+    "@aethervtt/shard-runtime": "0.2.0",
+    "@aethervtt/shard-scene": "0.2.0",
+    "@aethervtt/shard-text": "0.2.0",
+    "@aethervtt/shard-texture": "0.2.0",
+    "@aethervtt/shard-transform": "0.2.0"
   },
   "repository": {
     "type": "git",
@@ -37,6 +37,6 @@
     "provenance": true
   },
   "shard": {
-    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+    "buildSha": "32c22a3944ed23f5d1baa90bf7cc9fae724f5fd8"
   }
 }