@reventlessdev/reventless-local 3.0.0-alpha.245 → 3.0.0-alpha.246

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.246 (2026-09-07)
+
+### Bug Fixes
+
+* **local:** the event-history warning names the caller that asked ([53df2dc](https://github.com/ReventlessDev/reventless-core/commit/53df2dc71a8b4c434c4c5b8c9589c5154315d2e8))
+* **ui:** a declared slot module is named, not only written ([de000ba](https://github.com/ReventlessDev/reventless-core/commit/de000baf428249f64cfc719ed52df3760198b82a))
+### Features
+
+* **ui:** a deployment can name the module that draws its own surfaces ([b43828c](https://github.com/ReventlessDev/reventless-core/commit/b43828ca50cddd31f7aefae016669fcb7c059838))
+
+
 # 3.0.0-alpha.245 (2026-09-04)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-local",
-  "version": "3.0.0-alpha.245",
+  "version": "3.0.0-alpha.246",
   "description": "Local platform for Reventless (in-memory or SQLite backend, for development and testing without AWS)",
   "license": "Apache-2.0",
   "bin": {
@@ -40,18 +40,18 @@
     "@reventlessdev/rescript-node": "2.0.0-alpha.9",
     "@reventlessdev/rescript-mcp-sdk": "1.0.0-alpha.21",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
-    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.104",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.203",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.256",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.157",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.257",
+    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.105",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.158",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.121",
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.204",
     "@reventlessdev/reventless-seed": "1.0.0-alpha.19",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.129",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.120"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.130"
   },
   "devDependencies": {
     "rescript": "12.3.0",
     "sury-ppx": "11.0.0-rc.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.77"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.78"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/src/Platform.res

@@ -1471,6 +1471,10 @@ module MakeWithConfig = (
     // `makePlatform` serves the declared file in place of the host-shell
     // package's own dev-mode fallback, which an undeclared platform keeps.
     uiHintsFile?: string,
+    // `makePlatform` serves the declared module beside the hints file. No
+    // fallback to keep here: the host-shell package ships no slots module, so an
+    // undeclared platform serves none.
+    uiSlotsFile?: string,
     // `makePlatform` writes the curated manifest where the local host-shell
     // serves its static assets from, and points `config.json` at it.
     bakedManifest?: ReventlessInfra.Platform.bakedManifest,
@@ -1668,6 +1672,10 @@ module MakeWithConfig = (
     // declaring anything.
     ShellConfig.emit(
       ~bakedManifest=hostUiBundle->Option.flatMap(cfg => cfg.bakedManifest),
+      // Names the module `UiSlots.emit` serves below. Both or neither: a key
+      // without the file is a 404 the shell survives quietly, and a file without
+      // the key is a module nothing imports.
+      ~uiSlotsFile=?hostUiBundle->Option.flatMap(cfg => cfg.uiSlotsFile),
       ~shellConfig=hostUiBundle->Option.flatMap(cfg => cfg.shellConfig),
     )
     // Unconditional for the same reason, and one file over: it is also what
@@ -1687,6 +1695,15 @@ module MakeWithConfig = (
       ~uiHintsFile=hostUiBundle->Option.flatMap(cfg => cfg.uiHintsFile),
       ~onReload=LocalEvents_Server.broadcastUiHintsChanged,
     )
+    // The same pair for the module that draws what a hint cannot say. Also
+    // unconditional, and for a reason the hints file does not have: this is what
+    // removes a module a platform has stopped declaring, and leaving one behind
+    // would go on drawing regions with nothing in the deployment to explain it.
+    UiSlots.emit(~uiSlotsFile=hostUiBundle->Option.flatMap(cfg => cfg.uiSlotsFile))
+    let _ = UiSlots.watch(
+      ~uiSlotsFile=hostUiBundle->Option.flatMap(cfg => cfg.uiSlotsFile),
+      ~onReload=LocalEvents_Server.broadcastUiSlotsChanged,
+    )
     switch hostUiBundle->Option.flatMap(cfg => cfg.bakedManifest) {
     | None => ()
     | Some(cfg) => bakeManifest(~pluginComponents=plugins, ~config=cfg)

package/src/Platform.res.mjs

@@ -21,6 +21,7 @@ import * as Plugin$ReventlessCore from "@reventlessdev/reventless-core/src/plugi
 import * as Message$ReventlessCore from "@reventlessdev/reventless-core/src/Message.res.mjs";
 import * as Backend$ReventlessLocal from "./adapter/Backend.res.mjs";
 import * as UiHints$ReventlessLocal from "./UiHints.res.mjs";
+import * as UiSlots$ReventlessLocal from "./UiSlots.res.mjs";
 import * as Component$ReventlessCore from "@reventlessdev/reventless-core/src/components/Component.res.mjs";
 import * as LocalBus$ReventlessLocal from "./adapter/LocalBus.res.mjs";
 import * as Api_Naming$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/Api_Naming.res.mjs";
@@ -1314,9 +1315,11 @@ function MakeWithConfig(Config) {
       adminResources: []
     });
     subscribeToPluginEvents();
-    ShellConfig$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest), Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.shellConfig), undefined);
+    ShellConfig$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest), Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiSlotsFile), Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.shellConfig), undefined);
     UiHints$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiHintsFile), undefined);
     UiHints$ReventlessLocal.watch(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiHintsFile), undefined, LocalEvents_Server$ReventlessLocal.broadcastUiHintsChanged);
+    UiSlots$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiSlotsFile), undefined);
+    UiSlots$ReventlessLocal.watch(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiSlotsFile), undefined, LocalEvents_Server$ReventlessLocal.broadcastUiSlotsChanged);
     let cfg = Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest);
     if (cfg !== undefined) {
       bakeManifest(plugins$1, cfg);
@@ -3053,9 +3056,11 @@ function Make($star) {
       adminResources: []
     });
     subscribeToPluginEvents();
-    ShellConfig$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest), Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.shellConfig), undefined);
+    ShellConfig$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest), Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiSlotsFile), Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.shellConfig), undefined);
     UiHints$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiHintsFile), undefined);
     UiHints$ReventlessLocal.watch(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiHintsFile), undefined, LocalEvents_Server$ReventlessLocal.broadcastUiHintsChanged);
+    UiSlots$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiSlotsFile), undefined);
+    UiSlots$ReventlessLocal.watch(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiSlotsFile), undefined, LocalEvents_Server$ReventlessLocal.broadcastUiSlotsChanged);
     let cfg = Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest);
     if (cfg !== undefined) {
       bakeManifest(plugins$1, cfg);

package/src/ShellConfig.res

@@ -41,7 +41,11 @@ let manifestUrlOf = (config: ReventlessInfra.Platform.bakedManifest): string =>
 // caller matching no declared group gets and what every existing deployment has.
 let journeyManifestsKey = "journeyManifestUrls"
 
-let computedKeys = ["manifestUrl", journeyManifestsKey]
+let computedKeys = [
+  "manifestUrl",
+  journeyManifestsKey,
+  ReventlessCore.Platform_UiSlots.configKey,
+]
 
 /**
  The overlay this platform puts on top of the shipped `config.json`.
@@ -52,10 +56,23 @@ let computedKeys = ["manifestUrl", journeyManifestsKey]
  */
 let overlay = (
   ~bakedManifest: option<ReventlessInfra.Platform.bakedManifest>,
+  ~uiSlotsFile: option<string>=?,
   ~shellConfig: option<dict<JSON.t>>,
 ): dict<JSON.t> => {
   let out = Dict.make()
 
+  // `UiSlots` serves the module; this is what tells the shell to import it. The
+  // two are separate writes to separate files, which is exactly why the name
+  // they share is stated once in `Platform_UiSlots` — and why withdrawal has to
+  // clear both. The baseline does that half: drop the key here and the shipped
+  // `config.json` comes back without it.
+  uiSlotsFile->Option.forEach(_ =>
+    out->Dict.set(
+      ReventlessCore.Platform_UiSlots.configKey,
+      JSON.Encode.string(ReventlessCore.Platform_UiSlots.url),
+    )
+  )
+
   bakedManifest->Option.forEach(config => {
     out->Dict.set("manifestUrl", JSON.Encode.string(manifestUrlOf(config)))
     // Omitted entirely when nothing is declared, so a single-audience deployment
@@ -108,13 +125,14 @@ let readObject = (~path: string, ~label: string): dict<JSON.t> =>
  */
 let emit = (
   ~bakedManifest: option<ReventlessInfra.Platform.bakedManifest>,
+  ~uiSlotsFile: option<string>=?,
   ~shellConfig: option<dict<JSON.t>>,
   // Test seam. The baseline dance is the part of this module with state behind
   // it — "boot twice and the second write still starts from the shipped file" is
   // not a property a pure function can carry.
   ~dir: option<string>=?,
 ) => {
-  let overlay = overlay(~bakedManifest, ~shellConfig)
+  let overlay = overlay(~bakedManifest, ~uiSlotsFile?, ~shellConfig)
 
   switch (
     switch dir {

package/src/ShellConfig.res.mjs

@@ -8,6 +8,7 @@ import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
 import * as HostShellDist$ReventlessLocal from "./HostShellDist.res.mjs";
+import * as Platform_UiSlots$ReventlessCore from "@reventlessdev/reventless-core/src/admin/Platform_UiSlots.res.mjs";
 import * as Platform_BakedManifest$ReventlessCore from "@reventlessdev/reventless-core/src/admin/Platform_BakedManifest.res.mjs";
 
 let log = Logger$ReventlessCore.fromEnv();
@@ -24,11 +25,15 @@ let journeyManifestsKey = "journeyManifestUrls";
 
 let computedKeys = [
   "manifestUrl",
-  journeyManifestsKey
+  journeyManifestsKey,
+  Platform_UiSlots$ReventlessCore.configKey
 ];
 
-function overlay(bakedManifest, shellConfig) {
+function overlay(bakedManifest, uiSlotsFile, shellConfig) {
   let out = {};
+  Stdlib_Option.forEach(uiSlotsFile, param => {
+    out[Platform_UiSlots$ReventlessCore.configKey] = Platform_UiSlots$ReventlessCore.url;
+  });
   Stdlib_Option.forEach(bakedManifest, config => {
     out["manifestUrl"] = Platform_BakedManifest$ReventlessCore.urlForKey(config.key);
     let urls = Platform_BakedManifest$ReventlessCore.journeyUrls(config);
@@ -66,8 +71,8 @@ function readObject(path, label) {
   }
 }
 
-function emit(bakedManifest, shellConfig, dir) {
-  let overlay$1 = overlay(bakedManifest, shellConfig);
+function emit(bakedManifest, uiSlotsFile, shellConfig, dir) {
+  let overlay$1 = overlay(bakedManifest, uiSlotsFile, shellConfig);
   let dir$1 = dir !== undefined ? dir : HostShellDist$ReventlessLocal.dir();
   if (dir$1 === undefined) {
     if (Object.keys(overlay$1).length !== 0) {

package/src/UiSlots.res

@@ -0,0 +1,191 @@
+// Serves the AutoUI slot module a deployment declared, where the local host
+// shell serves its static assets from (`HostShellDist`).
+//
+// The same seam as `UiHints`, one file over: on AWS `uiSlotsFile` is read and
+// written verbatim as a `BucketObject` beside `config.json`, and locally the
+// declared file is copied into the served dist/ and watched, so editing a
+// renderer is a browser refresh rather than a platform restart.
+//
+// Two things differ from the hints file, and both are why this is its own
+// module rather than a parameter of that one.
+//
+// **There is no baseline, because there is nothing to protect.** The hints work
+// had to reckon with the host-shell package shipping its own `ui-hints.json` as
+// a dev fallback, which an undeclared platform goes on serving. The shell ships
+// no slots module, so "undeclared" means "no file" with no third party's opinion
+// underneath — and it should stay that way. A dev fallback here would be a
+// fallback for *appearance*, and inheriting a stranger's appearance is exactly
+// the failure that is hard to notice.
+//
+// So withdrawal removes the served file rather than restoring one. Any file at
+// this path is one this module wrote: nothing else in the dist/ is named it, and
+// the AWS bundle upload excludes the name for the same reason.
+//
+// **A broken module fails differently from broken hints.** Malformed hints
+// decode leniently and the surface survives; a module that throws at import
+// takes its whole registration with it. That is the shell's to report — log,
+// skip, continue — and the only thing this side owes is not to make it worse by
+// serving a stale copy after a failed edit. Hence no content check: serve what
+// is on disk, and let the consumer say what it could not use.
+
+let log = ReventlessCore.Logger.fromEnv()
+
+// Shared with the AWS deploy and with both `config.json` writers, because the
+// name the module is served under and the `uiSlotsUrl` naming it have to agree.
+let fileName = ReventlessCore.Platform_UiSlots.fileName
+
+/**
+ Write the declared slot module into the served `dist/`, or remove a previously
+ served one when nothing is declared.
+
+ A no-op when there is nothing to say and nothing was said before, so a platform
+ that declares no slots is byte-identical to one built before this existed.
+
+ Once a file is declared the write happens or fails loudly: a path that does not
+ resolve and a missing shell package are both the deployment's own mistake, and
+ both produce the same symptom if swallowed — regions that quietly go on being
+ drawn by their mode, which is indistinguishable from a renderer that was never
+ written.
+
+ What is deliberately *not* checked is the content. The deploy half cannot parse
+ a module either, and a check that only ran locally would let a file pass the
+ loop it was authored in and fail the one it ships to.
+ */
+let emit = (
+  ~uiSlotsFile: option<string>,
+  // Test seam, as in `UiHints.emit`: the removal on withdrawal is the part with
+  // state behind it, and "declare, then withdraw, and the file is gone" is not a
+  // property a pure function can carry.
+  ~dir: option<string>=?,
+) => {
+  // Read before anything is touched, so a bad declaration cannot leave the
+  // served file half-replaced.
+  let declared = uiSlotsFile->Option.map(path =>
+    switch NodeFs.readFileSync(path) {
+    | contents => contents
+    | exception _ =>
+      JsError.throwWithMessage(
+        `host UI ${fileName}: cannot read the declared uiSlotsFile at ${path} — ` ++
+        `the shell imports this file at boot, so a declaration pointing nowhere ` ++
+        `registers no renderers and says nothing about why.`,
+      )
+    }
+  )
+
+  switch (
+    switch dir {
+    | Some(_) as given => given
+    | None => HostShellDist.dir()
+    }
+  ) {
+  | None =>
+    // No shell installed is the ordinary case for a platform nobody points a
+    // browser at; only a declaration makes the missing package an error.
+    if declared->Option.isSome {
+      JsError.throwWithMessage(
+        `host UI ${fileName}: cannot resolve ${HostShellDist.package} from ${NodeProcess.cwd()} — ` ++
+        `the local shell imports its slot renderers from that package's dist/, so ` ++
+        `declaring a uiSlotsFile without the package installed would write nothing ` ++
+        `and leave every mode drawing its own regions.`,
+      )
+    }
+  | Some(dir) =>
+    let path = NodePath.join([dir, fileName])
+    switch declared {
+    | Some(contents) =>
+      NodeFs.writeFileSync(path, contents)
+      log.info(~comp="UiSlots", `wrote ${fileName} from the declared uiSlotsFile: ${path}`)
+    | None =>
+      // The counterpart to the hints baseline, and the reason this is a delete:
+      // leaving yesterday's renderers in place with nothing in the diff to
+      // explain them is the failure a baseline exists to prevent, and here the
+      // state to return to is "no file".
+      if NodeFs.existsSync(path) {
+        NodeFs.unlinkSync(path)
+        log.info(~comp="UiSlots", `removed ${fileName}: no uiSlotsFile is declared`)
+      }
+    }
+  }
+}
+
+/**
+ Re-copy the declared module into the served `dist/` whenever the file changes,
+ so editing a renderer is a browser refresh rather than a platform restart.
+
+ Local only, and deliberately so: on AWS the file is an object written once by a
+ deploy, and "the running deployment follows my working copy" is not a thing a
+ deployment should be able to do.
+
+ **Failures here are logged, not thrown**, which is the one place this parts
+ company with `emit`, for the reason `UiHints.watch` gives: at boot a declaration
+ that does not resolve is the deployment's mistake and taking the process down is
+ the point, while mid-session an unreadable file is almost always an editor
+ saving in two steps, and killing a running dev server over a keystroke would
+ make the feature worse than the restart it replaces.
+
+ A module mid-save is a narrower window than a JSON file mid-save, because
+ nothing here parses it: only a read that fails outright is caught, and a save
+ that lands a syntactically broken module is served as written. That is the
+ consumer's to report, and it reports it against the file the developer is
+ looking at.
+
+ `onReload` runs only after a re-copy actually succeeded, so a subscriber cannot
+ be told to re-import a file that did not change.
+ */
+let watch = (
+  ~uiSlotsFile: option<string>,
+  ~dir: option<string>=?,
+  ~onReload: unit => unit,
+): option<NodeFs.watcher> =>
+  uiSlotsFile->Option.flatMap(path => {
+    // Named apart from the `~dir` above, which is where the file is SERVED. This
+    // is where it is AUTHORED, and the two are never the same place — letting
+    // one shadow the other would re-serve the module into the source tree beside
+    // the file just edited.
+    let sourceDir = NodePath.dirname(path)
+    let base = NodePath.basename(path)
+    if !NodeFs.existsSync(sourceDir) {
+      // `emit` has already thrown on an unreadable declaration by the time this
+      // is reached, so this is the narrow case of a path whose directory went
+      // away between the two — worth a line, not worth a throw.
+      log.warn(
+        ~comp="UiSlots",
+        `not watching ${base}: ${sourceDir} does not exist, so changes to the declared ` ++
+        `uiSlotsFile will need a restart`,
+      )
+      None
+    } else {
+      // Editors coalesce badly: one save can raise `rename` and `change` within
+      // a millisecond of each other, and re-copying twice would re-import twice.
+      // The trailing timer collapses a burst into the single reload the
+      // developer actually made.
+      let pending = ref(None)
+      let reload = () => {
+        pending := None
+        switch emit(~uiSlotsFile, ~dir?) {
+        | () =>
+          log.info(~comp="UiSlots", `${base} changed — re-served`)
+          onReload()
+        | exception JsExn(e) =>
+          log.warn(
+            ~comp="UiSlots",
+            `${base} changed but could not be re-served: ` ++
+            e->JsExn.message->Option.getOr("unknown error"),
+          )
+        }
+      }
+      let watcher = NodeFs.watch(sourceDir, (_event, filename) =>
+        switch filename->Nullable.toOption {
+        | Some(name) if name == base =>
+          pending.contents->Option.forEach(clearTimeout)
+          pending := Some(setTimeout(reload, 50))
+        | _ => ()
+        }
+      )
+      log.info(~comp="UiSlots", `watching ${path} — edits are served without a restart`)
+      // Never the reason a process stays alive. A platform booted by a test that
+      // happens to declare slots would otherwise hold the event loop open and
+      // hang the run.
+      Some(watcher->NodeFs.watcherUnref)
+    }
+  })

package/src/UiSlots.res.mjs

@@ -0,0 +1,91 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
+import * as HostShellDist$ReventlessLocal from "./HostShellDist.res.mjs";
+import * as Platform_UiSlots$ReventlessCore from "@reventlessdev/reventless-core/src/admin/Platform_UiSlots.res.mjs";
+
+let log = Logger$ReventlessCore.fromEnv();
+
+function emit(uiSlotsFile, dir) {
+  let declared = Stdlib_Option.map(uiSlotsFile, path => {
+    try {
+      return Nodefs.readFileSync(path, "utf8");
+    } catch (exn) {
+      return Stdlib_JsError.throwWithMessage(`host UI ` + Platform_UiSlots$ReventlessCore.fileName + `: cannot read the declared uiSlotsFile at ` + path + ` — the shell imports this file at boot, so a declaration pointing nowhere registers no renderers and says nothing about why.`);
+    }
+  });
+  let dir$1 = dir !== undefined ? dir : HostShellDist$ReventlessLocal.dir();
+  if (dir$1 === undefined) {
+    if (Stdlib_Option.isSome(declared)) {
+      return Stdlib_JsError.throwWithMessage(`host UI ` + Platform_UiSlots$ReventlessCore.fileName + `: cannot resolve ` + HostShellDist$ReventlessLocal.$$package + ` from ` + process.cwd() + ` — the local shell imports its slot renderers from that package's dist/, so declaring a uiSlotsFile without the package installed would write nothing and leave every mode drawing its own regions.`);
+    } else {
+      return;
+    }
+  }
+  let path = Nodepath.join(dir$1, Platform_UiSlots$ReventlessCore.fileName);
+  if (declared !== undefined) {
+    Nodefs.writeFileSync(path, declared, "utf8");
+    return log.info("UiSlots", undefined, `wrote ` + Platform_UiSlots$ReventlessCore.fileName + ` from the declared uiSlotsFile: ` + path);
+  } else if (Nodefs.existsSync(path)) {
+    Nodefs.unlinkSync(path);
+    return log.info("UiSlots", undefined, `removed ` + Platform_UiSlots$ReventlessCore.fileName + `: no uiSlotsFile is declared`);
+  } else {
+    return;
+  }
+}
+
+function watch(uiSlotsFile, dir, onReload) {
+  return Stdlib_Option.flatMap(uiSlotsFile, path => {
+    let sourceDir = Nodepath.dirname(path);
+    let base = Nodepath.basename(path);
+    if (Nodefs.existsSync(sourceDir)) {
+      let pending = {
+        contents: undefined
+      };
+      let reload = () => {
+        pending.contents = undefined;
+        let val;
+        try {
+          val = emit(uiSlotsFile, dir);
+        } catch (raw_e) {
+          let e = Primitive_exceptions.internalToException(raw_e);
+          if (e.RE_EXN_ID === "JsExn") {
+            return log.warn("UiSlots", undefined, base + ` changed but could not be re-served: ` + Stdlib_Option.getOr(Stdlib_JsExn.message(e._1), "unknown error"));
+          }
+          throw e;
+        }
+        log.info("UiSlots", undefined, base + ` changed — re-served`);
+        onReload();
+      };
+      let watcher = Nodefs.watch(sourceDir, (_event, filename) => {
+        if (!(filename == null) && filename === base) {
+          Stdlib_Option.forEach(pending.contents, prim => {
+            clearTimeout(prim);
+          });
+          pending.contents = Primitive_option.some(setTimeout(reload, 50));
+          return;
+        }
+      });
+      log.info("UiSlots", undefined, `watching ` + path + ` — edits are served without a restart`);
+      return Primitive_option.some(watcher.unref());
+    }
+    log.warn("UiSlots", undefined, `not watching ` + base + `: ` + sourceDir + ` does not exist, so changes to the declared uiSlotsFile will need a restart`);
+  });
+}
+
+let fileName = Platform_UiSlots$ReventlessCore.fileName;
+
+export {
+  log,
+  fileName,
+  emit,
+  watch,
+}
+/* log Not a pure module */

package/src/adapter/Api/LocalEvents_Server.res

@@ -124,6 +124,24 @@ let broadcastUiHintsChanged = (): unit =>
     ~event=frame([("kind", JSON.Encode.string("uiHintsChanged"))]),
   )
 
+/** The channel a shell listens on to learn that this platform re-served its slot
+    module. A channel of its own rather than a second `kind` on the hints one,
+    because what a listener does about it differs: re-fetching hints is a data
+    refresh, while re-importing a module is not something a live page can
+    generally undo, and a listener has to be free to answer the two differently. */
+let devUiSlotsChannel = "/default/dev/uiSlots"
+
+/** Tell every connected shell that `ui-slots.js` has been re-served.
+
+    Carries no renderers, for the reason the hints signal carries no hints: this
+    is a cache-invalidation signal, not a second delivery path that could
+    disagree with the first. */
+let broadcastUiSlotsChanged = (): unit =>
+  broadcast(
+    ~channel=devUiSlotsChannel,
+    ~event=frame([("kind", JSON.Encode.string("uiSlotsChanged"))]),
+  )
+
 /** LocalBus bridge: a Source B change descriptor becomes a publish on the
     same channel the AWS StateTopic Lambda would use. No-op without matching
     subscribers, so wiring order against server start doesn't matter. */

package/src/adapter/Api/LocalEvents_Server.res.mjs

@@ -104,6 +104,15 @@ function broadcastUiHintsChanged() {
     ]]));
 }
 
+let devUiSlotsChannel = "/default/dev/uiSlots";
+
+function broadcastUiSlotsChanged() {
+  broadcast(devUiSlotsChannel, frame([[
+      "kind",
+      "uiSlotsChanged"
+    ]]));
+}
+
 function broadcastStateChange(name, descriptor) {
   let entityKey = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(descriptor), o => o["id"]), Stdlib_JSON.Decode.string), "");
   if (entityKey === "") {
@@ -339,6 +348,8 @@ export {
   broadcast,
   devUiHintsChannel,
   broadcastUiHintsChanged,
+  devUiSlotsChannel,
+  broadcastUiSlotsChanged,
   broadcastStateChange,
   decodeStringField,
   handleFrame,

package/src/adapter/EventHistory/EventHistoryResolvers_GraphQL.res

@@ -133,6 +133,50 @@ let readFilter = (args: JSON.t): filter => {
   }
 }
 
+// The filter keys a caller did send. A caller that lost its entity id still
+// sends the rest, so naming them is what tells a reader which client this was.
+let suppliedFilterKeys = (f: filter): array<string> =>
+  [
+    ("entityId", f.entityId->Option.isSome),
+    ("tagKey", f.tagKey->Option.isSome),
+    ("tagValue", f.tagValue->Option.isSome),
+    ("eventTypes", f.eventTypes->Option.isSome),
+    ("user", f.user->Option.isSome),
+    ("timeFrom", f.timeFrom->Option.isSome),
+    ("timeTo", f.timeTo->Option.isSome),
+  ]->Array.filterMap(((key, supplied)) => supplied ? Some(key) : None)
+
+/**
+ Who asked, named the way the caller named itself: the GraphQL operation name
+ off yoga's request params, and the identity `buildAuthContext` resolved.
+
+ Both are best-effort. A context carrying neither still logs the field, because
+ a warning that needs a well-formed context to appear is a warning that goes
+ missing exactly when something is wrong.
+ */
+let callerOf = (ctx: JSON.t): string => {
+  let operation =
+    ctx
+    ->JSON.Decode.object
+    ->Option.flatMap(d => d->Dict.get("params"))
+    ->Option.flatMap(JSON.Decode.object)
+    ->Option.flatMap(d => d->Dict.get("operationName"))
+    ->Option.flatMap(JSON.Decode.string)
+  let user = Auth_GraphqlContext.extractIdentity(ctx).userId
+  switch operation {
+  | Some(name) => `operation "${name}" as ${user}`
+  | None => `an unnamed operation as ${user}`
+  }
+}
+
+// What the caller sent, in one clause: who asked and which filter keys came
+// with it.
+let describeCaller = (~ctx: JSON.t, ~filter: filter): string =>
+  switch suppliedFilterKeys(filter) {
+  | [] => `${callerOf(ctx)}, with no filter`
+  | keys => `${callerOf(ctx)}, with filter [${keys->Array.join(", ")}]`
+  }
+
 // The tag a caller means: the precise (tagKey, tagValue) pair when given,
 // otherwise the `entityId` shortcut matched against ANY tag value.
 let matchesTag = (r: record, f: filter): bool =>
@@ -305,7 +349,7 @@ module Make = (Bus: LocalBus.T) => {
         let resolver: ReventlessGraphqlServer.GraphQL_ServerInstance.resolverFn = async (
           _root,
           args,
-          _ctx,
+          ctx,
         ) => {
           let f = readFilter(args)
           let records = switch Bus.getEventLogReplay(entry.busKey) {
@@ -315,10 +359,13 @@ module Make = (Bus: LocalBus.T) => {
             | None =>
               // Not a silent empty page: an aggregate log genuinely cannot be
               // read without an id, and a caller who omitted one asked a
-              // question this log cannot answer.
+              // question this log cannot answer. Named, because the client that
+              // sent it is what a reader needs next and the warning alone sent
+              // them hunting.
               log.warn(
                 ~comp="EventHistoryResolvers_GraphQL",
-                `${fieldName}: ${displayName} is an aggregate event log — it can only be read per entity. Supply filter.entityId.`,
+                `${fieldName}: ${displayName} is an aggregate event log — it can only be read per entity. ` ++
+                `Supply filter.entityId. Asked by ${describeCaller(~ctx, ~filter=f)}.`,
               )
               []
             }