@requence/service 0.8.2-edge.1151 → 0.8.2-edge.1155

package/build/index.js

@@ -3,7 +3,10 @@ import {
   PayloadTooLargeError,
   RequenceConnectionError,
   RequenceUnreachableError,
+  UITooLargeError,
   UnsupportedCapabilityError,
+  __commonJS,
+  __toESM,
   assertReachable,
   buildServiceClientProperties,
   buildServiceIdentityHeaders,
@@ -12,11 +15,21 @@ import {
   obfuscate,
   reachableFetch,
   readRequiredCapabilities,
+  simple_default,
   unsupportedCapabilities
-} from "./chunk-974rc2jy.js";
+} from "./chunk-gpyt51xn.js";
+
+// ../../node_modules/.bun/dlv@1.1.3/node_modules/dlv/dist/dlv.js
+var require_dlv = __commonJS((exports, module) => {
+  module.exports = function(t, e, l, n, o) {
+    for (e = e.split ? e.split(".") : e, n = 0;n < e.length; n++)
+      t = t ? t[e[n]] : o;
+    return t === o ? l : t;
+  };
+});
 
 // src/index.ts
-import fs from "node:fs";
+import fs3 from "node:fs";
 
 // ../helpers/src/utils/guards.ts
 import { z } from "zod/v4";
@@ -188,9 +201,88 @@ function createCallback(callback) {
   });
 }
 
+// ../helpers/src/utils/serviceRender.ts
+import { z as z6 } from "zod/v4";
+var serviceRenderSchema = z6.object({
+  component: z6.object({
+    id: z6.string(),
+    hash: z6.string(),
+    source: z6.string().nullable().default(null)
+  }),
+  props: z6.unknown(),
+  defaults: z6.unknown().optional(),
+  surfaceId: z6.string(),
+  devSession: z6.string().nullable().default(null)
+});
+var MAX_UI_SOURCE_BYTES = 1024 * 1024;
+var DEFAULT_SURFACE_ID = "default";
+var MAX_SURFACE_INTERACTION_BYTES = 64 * 1024;
+
+// ../helpers/src/utils/surfaceHandler.ts
+import { z as z7 } from "zod/v4";
+var SURFACE_HANDLER_TAG = "RequenceHandler";
+var handlerPathSchema = z7.array(z7.union([z7.string(), z7.int()]));
+var surfaceHandlerObjectSchema = z7.discriminatedUnion("lifetime", [
+  z7.object({
+    __REQUENCE_type: z7.literal(SURFACE_HANDLER_TAG),
+    lifetime: z7.literal("durable"),
+    uiId: z7.string(),
+    path: handlerPathSchema
+  }),
+  z7.object({
+    __REQUENCE_type: z7.literal(SURFACE_HANDLER_TAG),
+    lifetime: z7.literal("connection"),
+    uiId: z7.string(),
+    path: handlerPathSchema,
+    connectionId: z7.string(),
+    handlerId: z7.uuid()
+  })
+]);
+function isSurfaceHandlerObject(data) {
+  return surfaceHandlerObjectSchema.safeParse(data).success;
+}
+function serviceHandlerQueueName(dispatchQueue) {
+  return `${dispatchQueue}-handlers`;
+}
+var SURFACE_HANDLER_INVOCATION_TTL_MS = 60000;
+var SURFACE_HANDLER_QUEUE_ARGUMENTS = {
+  messageTtl: SURFACE_HANDLER_INVOCATION_TTL_MS,
+  deadLetterExchange: "error"
+};
+var surfaceHandlerInvocationSchema = z7.object({
+  taskId: z7.uuid(),
+  surface: z7.uuid(),
+  uiId: z7.string(),
+  path: handlerPathSchema,
+  arg: z7.unknown().optional()
+});
+var MAX_SURFACE_INTERACTION_ERROR_CHARS = 500;
+var SURFACE_INTERACTION_ERROR_HEADER = "surfaceInteractionError";
+var surfaceInteractionErrorReportSchema = z7.object({
+  surface: z7.uuid(),
+  message: z7.string()
+});
+
+// ../helpers/src/utils/uiRebuild.ts
+import { z as z8 } from "zod/v4";
+var UI_REBUILD_HEADER = "uiRebuild";
+var uiRebuildSchema = z8.object({
+  devSession: z8.string(),
+  uiId: z8.string(),
+  hash: z8.string(),
+  source: z8.string()
+});
+
+// ../helpers/src/utils/obj.ts
+var import_dlv = __toESM(require_dlv(), 1);
+var getByPath = import_dlv.default;
+
 // ../helpers/src/utils/amqpHeartbeat.ts
 var DEFAULT_AMQP_HEARTBEAT_SECONDS = 30;
 
+// src/createAmqpConnection.ts
+import { createHash as createHash2 } from "node:crypto";
+
 // ../helpers/src/msgpack/index.ts
 import { Buffer as Buffer2 } from "node:buffer";
 import { Packr, addExtension } from "msgpackr";
@@ -229,7 +321,7 @@ function unpackWire(buffer) {
   return wirePackr.unpack(buffer);
 }
 function wireByteLength(value) {
-  return wirePackr.pack(value).length;
+  return packWire(value).length;
 }
 var WIRE_CONTENT_TYPES = {
   json: "application/json",
@@ -257,7 +349,7 @@ function wireBodyByteLength(value, codec) {
 
 // src/createAmqpConnection.ts
 import { connect } from "amqp-connection-manager";
-import { z as z6 } from "zod/v4";
+import { z as z9 } from "zod/v4";
 
 // ../files/src/errors.ts
 class RequenceStreamTruncatedError extends Error {
@@ -832,7 +924,7 @@ function createMessageHandler() {
         }
         return offload(ctx, uploadUrl, json);
       }
-      const entries = Object.entries(body).map(([key, value]) => ({
+      const entries = Object.entries(body).filter(([key]) => !ctx.inlineKeys?.includes(key)).map(([key, value]) => ({
         key,
         valueJson: toOffloadJson(value),
         size: measure(value)
@@ -1091,8 +1183,25 @@ function assertTopLevelKeysPreserved(body, wrapped, handlerIndex) {
     throw new TransformError(`${label} changed a record body's top-level keys (removed: [${removed.join(", ")}], added: [${added.join(", ")}]) — wrapOutbound must preserve them`, []);
   }
 }
+// src/surfaceHandler.ts
+function createSurfaceHandlerValueHandler() {
+  return {
+    tag: SURFACE_HANDLER_TAG,
+    canHandle: (value) => typeof value === "function",
+    serialize(handler, ctx, path) {
+      return ctx.onSurfaceHandler(handler, path);
+    },
+    isReference: (value) => isSurfaceHandlerObject(value),
+    deserialize() {
+      throw new Error("a surface handler reference is outbound-only — it is invoked by its own message, never reconstructed");
+    }
+  };
+}
+
 // src/transformer.ts
-var transformer = createTransformer().withHandler(createRequenceFileHandler()).withHandler(createRequenceStreamHandler()).withHandler(createRequenceCallbackHandler()).withHandler(createClaimCheckHandler());
+var byteReferences = createTransformer().withHandler(createRequenceFileHandler()).withHandler(createRequenceStreamHandler());
+var transformer = byteReferences.withHandler(createRequenceCallbackHandler()).withHandler(createClaimCheckHandler());
+var renderTransformer = byteReferences.withHandler(createSurfaceHandlerValueHandler()).withHandler(createClaimCheckHandler());
 var passthroughHandler = (handler) => ({
   tag: handler.tag,
   passthrough: true,
@@ -1109,7 +1218,7 @@ var passthroughInboundTransformer = createTransformer().withHandler(passthroughH
 
 // src/boundary.ts
 function createOutboundBoundary(base) {
-  const warn = base.warn ?? ((message, error) => error === undefined ? console.warn(message) : console.warn(message, error));
+  const warn = base.warn ?? ((message, error) => error === undefined ? simple_default.warn(message) : simple_default.warn(message, error));
   const ledger = [];
   const errors = [];
   const codec = base.wireCodec ?? "json";
@@ -1132,6 +1241,7 @@ function createOutboundBoundary(base) {
         measure,
         outputName: opts.outputName ?? null,
         onCallback: opts.onCallback,
+        inlineKeys: opts.inlineKeys,
         ...opts.bestEffort ? {
           onOffloadFail: (error) => warn("offload failed (best-effort log path):", error),
           onOffloadSkip: () => warn("offload skipped: no upload transport configured")
@@ -1147,7 +1257,10 @@ function createOutboundBoundary(base) {
           return;
         }
       }
-      const { value, done } = await withRequenceStreams(() => transformer.outbound(data, ctx));
+      const { value, done } = await withRequenceStreams(() => opts.onSurfaceHandler ? renderTransformer.outbound(data, {
+        ...ctx,
+        onSurfaceHandler: opts.onSurfaceHandler
+      }) : transformer.outbound(data, ctx));
       track(done);
       return value;
     },
@@ -1234,6 +1347,13 @@ async function createContextHelper(options) {
       };
     },
     defer: options.onDefer,
+    render(ui, props, renderOptions) {
+      options.onRender({
+        ui,
+        props,
+        surfaceId: renderOptions?.surfaceId ?? DEFAULT_SURFACE_ID
+      });
+    },
     debug: {
       log(...data) {
         options.onLog("log", data);
@@ -1264,8 +1384,105 @@ async function createContextHelper(options) {
 }
 var handlerStorage = new AsyncLocalStorage2;
 
+// src/uiWatch.ts
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+var REBUILD_DEBOUNCE_MS = 100;
+var registrations = new Set;
+var listeners = new Set;
+var watching = false;
+function warn(message) {
+  listeners.forEach((listener) => listener.onWarning(message));
+}
+function registerUI(ui, filePath) {
+  const clash = [...registrations].find((existing) => existing.ui.id === ui.id);
+  if (clash) {
+    throw new Error(`two components share the UI id "${ui.id}" (${clash.path} and ${filePath}) — pass an explicit id: createUI({ url, id: '…' })`);
+  }
+  const registration = { ui, path: filePath };
+  registrations.add(registration);
+  if (watching) {
+    startWatching(registration);
+  }
+}
+function findUIById(id) {
+  return [...registrations].find((entry) => entry.ui.id === id)?.ui;
+}
+function watchUIRebuilds(listener) {
+  listeners.add(listener);
+  if (!watching) {
+    watching = true;
+    registrations.forEach(startWatching);
+  }
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size > 0) {
+      return;
+    }
+    watching = false;
+    for (const registration of registrations) {
+      registration.stop?.();
+      registration.stop = undefined;
+    }
+  };
+}
+function startWatching(registration) {
+  if (registration.stop) {
+    return;
+  }
+  const directory = path.dirname(registration.path);
+  let timer;
+  let watcher;
+  try {
+    watcher = fs.watch(directory, () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => reload(registration), REBUILD_DEBOUNCE_MS);
+      timer.unref?.();
+    });
+  } catch (error) {
+    warn(`Requence: cannot watch ${registration.path} for rebuilds: ${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+  watcher.unref?.();
+  watcher.on("error", (error) => {
+    warn(`Requence: stopped watching ${registration.path}: ${error.message}`);
+  });
+  registration.stop = () => {
+    clearTimeout(timer);
+    watcher.close();
+  };
+}
+function reload(registration) {
+  let bundle;
+  try {
+    bundle = fs.readFileSync(registration.path);
+  } catch {
+    return;
+  }
+  const hash = createHash("sha256").update(bundle).digest("hex");
+  if (hash === registration.ui.hash) {
+    return;
+  }
+  if (bundle.byteLength > MAX_UI_SOURCE_BYTES) {
+    if (hash !== registration.refusedHash) {
+      registration.refusedHash = hash;
+      warn(`Requence: rebuilt component ${registration.path} is ${bundle.byteLength} bytes, over the ${MAX_UI_SOURCE_BYTES} limit — keeping the previous bundle`);
+    }
+    return;
+  }
+  registration.ui.hash = hash;
+  registration.ui.source = bundle.toString("utf-8");
+  for (const listener of [...listeners]) {
+    listener.onRebuild(registration.ui);
+  }
+}
+
 // src/createAmqpConnection.ts
-var messageKeySchema = z6.string().transform((str) => deobfuscate(str)).pipe(z6.tuple([z6.uuid(), z6.uuid()]).rest(z6.string())).transform((arr) => ({
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var messageKeySchema = z9.string().transform((str) => deobfuscate(str)).pipe(z9.tuple([z9.uuid(), z9.uuid()]).rest(z9.string())).transform((arr) => ({
   taskId: arr[0],
   messageId: arr[1],
   uploadUrl: arr[2] || undefined,
@@ -1273,12 +1490,12 @@ var messageKeySchema = z6.string().transform((str) => deobfuscate(str)).pipe(z6.
   maxPayloadSize: arr[4] && Number.isFinite(Number(arr[4])) ? Number(arr[4]) : undefined,
   maxFileSize: arr[5] && Number.isFinite(Number(arr[5])) ? Number(arr[5]) : undefined
 }));
-var headerSchema = z6.object({
-  properties: z6.object({
-    correlationId: z6.uuid(),
-    headers: z6.object({
-      taskId: z6.uuid(),
-      mode: z6.enum(["LINEAR", "CONTINUOUS"]).default("LINEAR")
+var headerSchema = z9.object({
+  properties: z9.object({
+    correlationId: z9.uuid(),
+    headers: z9.object({
+      taskId: z9.uuid(),
+      mode: z9.enum(["LINEAR", "CONTINUOUS"]).default("LINEAR")
     })
   })
 }).transform((msg) => ({
@@ -1286,62 +1503,66 @@ var headerSchema = z6.object({
   taskId: msg.properties.headers.taskId,
   mode: msg.properties.headers.mode
 }));
-var payloadSchema = z6.object({
-  content: z6.instanceof(Buffer),
-  properties: z6.object({ contentType: z6.string().optional() })
-}).transform((msg) => decodeWireBody(msg.content, msg.properties.contentType)).pipe(z6.object({
-  input: z6.unknown(),
-  configuration: z6.unknown(),
-  options: z6.object({
-    uploadUrl: z6.url().optional(),
-    streamUrl: z6.url().optional(),
-    maxPayloadSize: z6.number().optional(),
-    maxFileSize: z6.number().optional()
+var payloadSchema = z9.object({
+  content: z9.instanceof(Buffer),
+  properties: z9.object({ contentType: z9.string().optional() })
+}).transform((msg) => decodeWireBody(msg.content, msg.properties.contentType)).pipe(z9.object({
+  input: z9.unknown().optional(),
+  configuration: z9.unknown().optional(),
+  options: z9.object({
+    uploadUrl: z9.url().optional(),
+    streamUrl: z9.url().optional(),
+    maxPayloadSize: z9.number().optional(),
+    maxFileSize: z9.number().optional()
   })
 }));
-var backchannelMessageSchema = z6.object({
-  content: z6.instanceof(Buffer),
-  properties: z6.object({
-    correlationId: z6.string(),
-    contentType: z6.string().optional()
+var backchannelMessageSchema = z9.object({
+  content: z9.instanceof(Buffer),
+  properties: z9.object({
+    correlationId: z9.string(),
+    contentType: z9.string().optional(),
+    headers: z9.object({ taskId: z9.uuid().optional() }).optional().catch(undefined)
   })
 }).transform((message) => ({
   ...message,
   content: decodeWireBody(message.content, message.properties.contentType)
-})).pipe(z6.object({
-  content: z6.discriminatedUnion("type", [
-    z6.object({
-      type: z6.literal("stop")
+})).pipe(z9.object({
+  content: z9.discriminatedUnion("type", [
+    z9.object({
+      type: z9.literal("stop")
     }),
-    z6.object({
-      type: z6.literal("callback"),
-      callbackId: z6.uuid(),
-      arg: z6.any()
+    z9.object({
+      type: z9.literal("callback"),
+      callbackId: z9.uuid(),
+      arg: z9.any().optional(),
+      surface: z9.uuid().optional()
     })
   ]),
-  properties: z6.object({
-    correlationId: z6.string()
+  properties: z9.object({
+    correlationId: z9.string(),
+    headers: z9.object({ taskId: z9.uuid().optional() }).optional().catch(undefined)
   })
 })).transform((message) => ({
   payload: message.content,
-  messageId: message.properties.correlationId
+  messageId: message.properties.correlationId,
+  taskId: message.properties.headers?.taskId
 }));
 var abortSymbol = Symbol();
-var connectionOptionsSchema = z6.object({
-  url: z6.union([
-    z6.string().regex(/^amqps?:\/\/(.+):(.+)@(.+)$/).transform((str) => new URL(str)),
-    z6.instanceof(URL).refine((url) => url.protocol.match(/^amqps?:/), "Wrong protocol")
+var connectionOptionsSchema = z9.object({
+  url: z9.union([
+    z9.string().regex(/^amqps?:\/\/(.+):(.+)@(.+)$/).transform((str) => new URL(str)),
+    z9.instanceof(URL).refine((url) => url.protocol.match(/^amqps?:/), "Wrong protocol")
   ]),
-  version: z6.string(),
-  name: z6.string().optional(),
-  devOverlay: z6.string().optional(),
-  silent: z6.boolean().optional(),
-  prefetch: z6.number().int().optional(),
-  connectionTimeout: z6.number().positive().default(3000),
-  heartbeatInterval: z6.number().int().positive().optional(),
-  connectionOptions: z6.any().optional(),
-  maxMessageSize: z6.number().int().positive().default(128 * 1024 * 1024),
-  passthroughByteReferences: z6.boolean().optional()
+  version: z9.string(),
+  name: z9.string().optional(),
+  devOverlay: z9.string().optional(),
+  silent: z9.boolean().optional(),
+  prefetch: z9.number().int().optional(),
+  connectionTimeout: z9.number().positive().default(3000),
+  heartbeatInterval: z9.number().int().positive().optional(),
+  connectionOptions: z9.any().optional(),
+  maxMessageSize: z9.number().int().positive().default(128 * 1024 * 1024),
+  passthroughByteReferences: z9.boolean().optional()
 });
 function isMessageHandlerGenerator(handler) {
   return handler.constructor.name === "GeneratorFunction" || handler.constructor.name === "AsyncGeneratorFunction";
@@ -1384,6 +1605,7 @@ function createConnection({
   ...rest
 }, messageHandler) {
   const passthroughByteReferences = rest.passthroughByteReferences ?? false;
+  const canRegisterCallbacks = isMessageHandlerGenerator(messageHandler);
   const baseQueue = `${url.username}@${version}`;
   const queue = devOverlay ? `${baseQueue}-dev-overlay-${devOverlay}` : baseQueue;
   const exchange = url.username;
@@ -1393,7 +1615,7 @@ function createConnection({
       clientProperties: {
         ...connectionOptions?.clientProperties,
         ...buildServiceClientProperties({
-          libVersion: "javascript@0.8.2-edge.1151",
+          libVersion: "javascript@0.8.2-edge.1155",
           serviceVersion: version,
           name,
           devOverlay: Boolean(devOverlay)
@@ -1404,14 +1626,14 @@ function createConnection({
   });
   connection.on("disconnect", ({ err }) => {
     if (!silent && err) {
-      console.error("Requence AMQP connection lost:", err.message);
+      simple_default.error("Requence AMQP connection lost:", err.message);
     }
     onConnectionStateChange?.({ connected: false, err });
   });
   let hasConnected = false;
   connection.on("connect", () => {
     if (hasConnected && !silent) {
-      console.info("Requence AMQP reconnected");
+      simple_default.info("Requence AMQP reconnected");
     }
     hasConnected = true;
     onConnectionStateChange?.({ connected: true });
@@ -1443,7 +1665,9 @@ function createConnection({
     connection.addListener("connectFailed", handleConnectFailed);
   });
   const connectionId = crypto.randomUUID();
-  const backchannelQueue = `${baseQueue}-backchannel-${connectionId}`;
+  const devSession = devOverlay ? `${baseQueue}#${createHash2("sha256").update(devOverlay).digest("hex").slice(0, 16)}` : "";
+  const backchannelQueue = `${queue}-backchannel-${connectionId}`;
+  const sentComponents = new Set;
   const generatorTerminators = new Map;
   const callbacks = new Map;
   const backchannelInbound = createInboundBoundary(passthroughByteReferences ? { transformer: passthroughInboundTransformer } : {});
@@ -1473,8 +1697,13 @@ function createConnection({
             break;
           }
           case "callback": {
+            const { surface } = backchannelMessage.payload;
+            const { taskId } = backchannelMessage;
+            const report = surface && taskId ? (message2) => reportInteractionFailure({ taskId, surface, message: message2 }) : () => {};
             const entry = callbacks.get(backchannelMessage.payload.callbackId);
             if (!entry) {
+              simple_default.warn(`Requence: dropped an invocation of callback |${backchannelMessage.payload.callbackId}| — nothing is registered under it, so the message that registered it has settled`);
+              report("the process that drew this surface has finished with it, so nothing ran the handler");
               break;
             }
             let arg;
@@ -1483,10 +1712,16 @@ function createConnection({
                 onCallbackInvoke: entry.onCallbackInvoke
               });
             } catch (error) {
-              console.warn(`dropped callback invocation |${backchannelMessage.payload.callbackId}|: argument rehydration failed`, error instanceof Error ? error.message : error);
+              simple_default.warn(`dropped callback invocation |${backchannelMessage.payload.callbackId}|: argument rehydration failed`, error instanceof Error ? error.message : error);
+              report("the interaction could not be delivered: its argument could not be read");
               break;
             }
-            entry.callback(arg);
+            try {
+              await entry.callback(arg);
+            } catch (error) {
+              simple_default.error(`Requence: callback |${backchannelMessage.payload.callbackId}| threw:`, error instanceof Error ? error.stack ?? error.message : error);
+              report(`the handler failed: ${errorText(error)}`);
+            }
             break;
           }
         }
@@ -1497,7 +1732,101 @@ function createConnection({
   });
   channelWrapper.on("error", (err) => {
     if (!silent) {
-      console.error("Requence AMQP channel error:", err.message);
+      simple_default.error("Requence AMQP channel error:", err.message);
+    }
+  });
+  const reportInteractionFailure = (params) => {
+    channelWrapper.publish(exchange, "", Buffer.from(JSON.stringify({
+      surface: params.surface,
+      message: params.message.slice(0, MAX_SURFACE_INTERACTION_ERROR_CHARS)
+    })), {
+      contentType: "application/json",
+      persistent: true,
+      headers: {
+        taskId: params.taskId,
+        [SURFACE_INTERACTION_ERROR_HEADER]: true
+      }
+    }).catch((error) => {
+      simple_default.error(`Requence: could not report a failed surface interaction on |${params.surface}|:`, error instanceof Error ? error.message : error);
+    });
+  };
+  const publishBundleSwap = (ui) => {
+    const swap = {
+      devSession,
+      uiId: ui.id,
+      hash: ui.hash,
+      source: ui.source
+    };
+    channelWrapper.publish(exchange, "", Buffer.from(JSON.stringify(swap)), {
+      contentType: "application/json",
+      persistent: true,
+      headers: { [UI_REBUILD_HEADER]: true }
+    }).then(() => {
+      if (!silent) {
+        simple_default.info(`Requence: component |${ui.id}| rebuilt (${ui.hash.slice(0, 12)}) — swapped on every surface of this dev session`);
+      }
+    }).catch((error) => {
+      simple_default.error(`Requence: could not publish the rebuild of |${ui.id}|:`, error instanceof Error ? error.message : error);
+    });
+  };
+  const stopUIWatch = devSession ? watchUIRebuilds({
+    onRebuild: publishBundleSwap,
+    onWarning: (warning) => {
+      if (!silent) {
+        simple_default.warn(warning);
+      }
+    }
+  }) : undefined;
+  const runHandlerInvocation = async (raw) => {
+    const parsed = surfaceHandlerInvocationSchema.safeParse(raw);
+    if (!parsed.success) {
+      simple_default.error("Requence: dropped a malformed surface handler invocation:", parsed.error.message);
+      return;
+    }
+    const { taskId, surface, uiId, path: path2, arg } = parsed.data;
+    const where = `UI |${uiId}| prop |${path2.join(".") || "<root>"}| (task |${taskId}|)`;
+    const report = (message) => reportInteractionFailure({ taskId, surface, message });
+    const ui = findUIById(uiId);
+    if (!ui) {
+      simple_default.error(`Requence: no component registered as |${uiId}| — dropped a handler invocation for ${where}`);
+      report(`the service has no component registered as "${uiId}", so nothing ran the handler`);
+      return;
+    }
+    const handler = getByPath(ui.defaults, path2);
+    if (typeof handler !== "function") {
+      simple_default.error(`Requence: no handler at ${where} — the component's defaults have ${handler === undefined ? "nothing" : typeof handler} there`);
+      report(`this component has no handler at "${path2.join(".") || "<root>"}", so nothing ran`);
+      return;
+    }
+    try {
+      await handler(arg);
+    } catch (error) {
+      report(`the handler failed: ${errorText(error)}`);
+      throw error;
+    }
+  };
+  const handlerQueue = serviceHandlerQueueName(queue);
+  const handlerChannelWrapper = connection.createChannel({
+    async setup(channel) {
+      await channel.assertQueue(handlerQueue, SURFACE_HANDLER_QUEUE_ARGUMENTS);
+      await channel.bindQueue(handlerQueue, "service", handlerQueue);
+      await channel.prefetch(prefetch);
+      await channel.consume(handlerQueue, async (message) => {
+        if (!message) {
+          return;
+        }
+        try {
+          await runHandlerInvocation(JSON.parse(message.content.toString()));
+        } catch (error) {
+          simple_default.error("Requence: surface handler threw:", error instanceof Error ? error.stack ?? error.message : error);
+        }
+        safeAck(channel, message);
+      });
+    }
+  });
+  handlerChannelWrapper.on("error", (err) => {
+    if (!silent) {
+      simple_default.error("Requence AMQP handler channel error:", err.message);
     }
   });
   const publish = ({
@@ -1574,6 +1903,71 @@ function createConnection({
       }
     };
   };
+  const buildRender = (deps) => {
+    const registerSurfaceHandler = (ui, handler, payloadPath) => {
+      const [layer, ...path2] = payloadPath;
+      if (layer === "defaults") {
+        return {
+          __REQUENCE_type: SURFACE_HANDLER_TAG,
+          lifetime: "durable",
+          uiId: ui.id,
+          path: path2
+        };
+      }
+      if (layer !== "props") {
+        throw new Error(`a function in a render payload is only a handler under props or defaults (found at "${payloadPath.join(".")}")`);
+      }
+      const { sourceId, callbackId } = deps.registerCallback(handler);
+      return {
+        __REQUENCE_type: SURFACE_HANDLER_TAG,
+        lifetime: "connection",
+        uiId: ui.id,
+        path: path2,
+        connectionId: sourceId,
+        handlerId: callbackId
+      };
+    };
+    const renderSurface = (params) => {
+      const index = deps.nextIndex();
+      const sentKey = `${deps.taskId}:${params.ui.hash}`;
+      const withSource = !sentComponents.has(sentKey);
+      if (withSource) {
+        sentComponents.add(sentKey);
+      }
+      const issue = () => deps.outbound.send({
+        component: withSource ? {
+          id: params.ui.id,
+          hash: params.ui.hash,
+          source: params.ui.source
+        } : { id: params.ui.id, hash: params.ui.hash },
+        props: params.props,
+        ...params.ui.defaults === undefined ? {} : { defaults: params.ui.defaults },
+        surfaceId: params.surfaceId,
+        devSession: devSession || null
+      }, {
+        outputName: null,
+        inlineKeys: ["component", "defaults"],
+        onSurfaceHandler: (handler, path2) => registerSurfaceHandler(params.ui, handler, path2)
+      }).then((data) => publish({
+        index,
+        version,
+        messageId: deps.messageId,
+        taskId: deps.taskId,
+        data,
+        render: true,
+        ...deps.priority === undefined ? {} : { priority: deps.priority },
+        ...deps.epoch === undefined ? {} : { epoch: deps.epoch }
+      }));
+      const gated = deps.gate?.();
+      deps.outbound.track((gated ? gated.then(issue) : issue()).catch((error) => {
+        if (withSource) {
+          sentComponents.delete(sentKey);
+        }
+        throw error;
+      }));
+    };
+    return renderSurface;
+  };
   channelWrapper.addSetup(async (channel) => {
     channel.consume(queue, async (message) => {
       if (!message) {
@@ -1623,7 +2017,7 @@ function createConnection({
           maxFileSize: payload.options.maxFileSize,
           wireCodec: dispatchCodec,
           signal: abortController.signal,
-          warn: (msg, error) => console.warn(`${msg} (task ${taskId})`, error instanceof Error ? error.message : error ?? "")
+          warn: (msg, error) => simple_default.warn(`${msg} (task ${taskId})`, error instanceof Error ? error.message : error ?? "")
         });
         const dispatchInvocation = (params) => {
           outbound.track(outbound.send(params.arg, {
@@ -1642,6 +2036,21 @@ function createConnection({
             epoch
           })));
         };
+        const publishDeps = {
+          outbound,
+          registerCallback,
+          taskId,
+          messageId,
+          nextIndex: () => publishIndex++,
+          epoch,
+          priority: message.properties.priority
+        };
+        const onRender = buildRender({
+          ...publishDeps,
+          registerCallback: canRegisterCallbacks ? registerCallback : () => {
+            throw new Error("A LINEAR version handler may not register function props — the registration dies when the handler returns. To wait for a viewer, call context.defer() and declare the handler in the UI defaults instead: a durable handler outlives this process.");
+          }
+        });
         const [extendedContext, terminatePromise] = await createContextHelper({
           taskId,
           input: payload.input,
@@ -1649,15 +2058,7 @@ function createConnection({
           abortController,
           passthroughByteReferences,
           sends: {
-            ...buildSendApi({
-              outbound,
-              registerCallback,
-              taskId,
-              messageId,
-              nextIndex: () => publishIndex++,
-              epoch,
-              priority: message.properties.priority
-            }),
+            ...buildSendApi(publishDeps),
             invokeCallback: (ref, arg) => dispatchInvocation({
               sourceId: ref.sourceId,
               callbackId: ref.callbackId,
@@ -1685,6 +2086,7 @@ function createConnection({
               });
             });
           },
+          onRender,
           onDefer(reason) {
             deferred = true;
             deferredReason = reason || null;
@@ -1701,7 +2103,7 @@ function createConnection({
           begin: true,
           epoch,
           ...buildServiceIdentityHeaders({
-            libVersion: "javascript@0.8.2-edge.1151",
+            libVersion: "javascript@0.8.2-edge.1155",
             name
           })
         });
@@ -1741,7 +2143,7 @@ function createConnection({
               const { value: result, done } = next;
               if (deferred) {
                 deferred = false;
-                console.warn("returning a value in a deferred message resets the deferred status");
+                simple_default.warn("returning a value in a deferred message resets the deferred status");
               }
               const { value: rawValue, outputName } = unwrapOutputValue(result);
               const value = await outbound.send(rawValue, {
@@ -1775,7 +2177,7 @@ function createConnection({
             }
           });
           if (deferred && value) {
-            console.warn("returning a value in a deferred message resets the deferred status");
+            simple_default.warn("returning a value in a deferred message resets the deferred status");
             deferred = false;
           }
           if (!deferred || value) {
@@ -1834,14 +2236,14 @@ function createConnection({
           };
           channelWrapper.publish(`${exchange}-retry`, version, message.content, properties).catch((publishError) => {
             if (!silent) {
-              console.error("Failed to republish message for retry:", publishError);
+              simple_default.error("Failed to republish message for retry:", publishError);
             }
           });
           return;
         }
         if (error instanceof UnsupportedCapabilityError) {
           if (!silent) {
-            console.error(error.message);
+            simple_default.error(error.message);
           }
           if (!acked) {
             safeAck(channel, message);
@@ -1857,7 +2259,7 @@ function createConnection({
             }
           }).catch((publishError) => {
             if (!silent) {
-              console.error("Failed to publish capability mismatch message:", publishError);
+              simple_default.error("Failed to publish capability mismatch message:", publishError);
             }
           });
           return;
@@ -1876,7 +2278,7 @@ function createConnection({
             }
           }).catch((publishError) => {
             if (!silent) {
-              console.error("Failed to publish abort message:", publishError);
+              simple_default.error("Failed to publish abort message:", publishError);
             }
           });
           return;
@@ -1889,8 +2291,8 @@ function createConnection({
         }
         if (error instanceof Error) {
           if (!silent) {
-            console.error("Encountered an error inside service handler:");
-            console.error(error);
+            simple_default.error("Encountered an error inside service handler:");
+            simple_default.error(error);
           }
           if (!acked) {
             safeAck(channel, message);
@@ -1906,7 +2308,7 @@ function createConnection({
             }
           }).catch((publishError) => {
             if (!silent) {
-              console.error("Failed to publish exception message:", publishError);
+              simple_default.error("Failed to publish exception message:", publishError);
             }
           });
           return;
@@ -1924,6 +2326,8 @@ function createConnection({
   const activeMessageKeys = new Set;
   const api = {
     close: async () => {
+      stopUIWatch?.();
+      await handlerChannelWrapper.close();
       await channelWrapper.close();
       await connection.close();
     },
@@ -1967,15 +2371,24 @@ function createConnection({
           propertyPath: params.propertyPath
         })));
       };
+      const publishDeps = {
+        outbound,
+        registerCallback,
+        taskId,
+        messageId,
+        nextIndex: () => publishIndex++,
+        gate: activeMessage
+      };
+      const renderSurface = buildRender(publishDeps);
       const sendApi = {
-        ...buildSendApi({
-          outbound,
-          registerCallback,
-          taskId,
-          messageId,
-          nextIndex: () => publishIndex++,
-          gate: activeMessage
-        }),
+        ...buildSendApi(publishDeps),
+        render(ui, props, renderOptions) {
+          renderSurface({
+            ui,
+            props,
+            surfaceId: renderOptions?.surfaceId ?? DEFAULT_SURFACE_ID
+          });
+        },
         async abort(error) {
           await activeMessage();
           channelWrapper.publish(`${exchange}-retry`, "operator", error instanceof Error ? error.message : error, {
@@ -2027,6 +2440,30 @@ function createConnection({
   };
   return api;
 }
+// src/ui.ts
+import { createHash as createHash3 } from "node:crypto";
+import fs2 from "node:fs";
+import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
+function createUI(target, defaults) {
+  const options = target instanceof URL ? { url: target } : target;
+  if (!(options?.url instanceof URL) || options.url.protocol !== "file:") {
+    throw new Error("createUI needs a file URL to the built component: new URL('./component.js', import.meta.url)");
+  }
+  const path2 = fileURLToPath(options.url);
+  const bundle = fs2.readFileSync(path2);
+  if (bundle.byteLength > MAX_UI_SOURCE_BYTES) {
+    throw new UITooLargeError(path2, bundle.byteLength, MAX_UI_SOURCE_BYTES);
+  }
+  const ui = {
+    id: options.id ?? basename(path2),
+    hash: createHash3("sha256").update(bundle).digest("hex"),
+    source: bundle.toString("utf-8"),
+    ...defaults === undefined ? {} : { defaults: { ...defaults } }
+  };
+  registerUI(ui, path2);
+  return ui;
+}
 // src/utils.ts
 function isAsyncIterable(iterable) {
   return typeof iterable[Symbol.asyncIterator] === "function";
@@ -2124,7 +2561,7 @@ function resolveConnectionOptions(connectionOptions) {
   if (caEnv) {
     tlsDefaults.ca = caEnv;
   } else if (caFileEnv) {
-    tlsDefaults.ca = fs.readFileSync(caFileEnv);
+    tlsDefaults.ca = fs3.readFileSync(caFileEnv);
   }
   if (Object.keys(tlsDefaults).length === 0) {
     return connectionOptions;
@@ -2134,10 +2571,11 @@ function resolveConnectionOptions(connectionOptions) {
 var pkgJson;
 function loadPkgJson() {
   if (!pkgJson) {
-    pkgJson = JSON.parse(fs.readFileSync("package.json", "utf-8"));
+    pkgJson = JSON.parse(fs3.readFileSync("package.json", "utf-8"));
   }
   return pkgJson;
 }
+var didWarnDevToken = false;
 function createService(optionsOrVersion, optionalMessageHandler) {
   let options;
   let messageHandler;
@@ -2182,6 +2620,10 @@ function createService(optionsOrVersion, optionalMessageHandler) {
       throw new Error("invalid dev token: access token and dev token belong to different requence instances");
     }
     devOverlay = devParts[1];
+    if (!didWarnDevToken) {
+      didWarnDevToken = true;
+      simple_default.warn("Requence: started with a |dev token| — this worker consumes a personal dev-overlay queue instead of the deployed version, and that queue is deleted shortly after the process stops. Do not deploy with one: unset |REQUENCE_DEV_TOKEN| / |REQUENCE_SERVICE_DEV_TOKEN|, or remove |requence.devToken| from package.json.");
+    }
   }
   const envMaxMessageSize = process.env.REQUENCE_MAX_MESSAGE_SIZE ? Number(process.env.REQUENCE_MAX_MESSAGE_SIZE) : undefined;
   return createConnection({
@@ -2199,11 +2641,13 @@ export {
   wrapIterable,
   reachableFetch,
   isUnreachableStatus,
+  createUI,
   createService,
   createCallback,
   asyncEventEmitter,
   assertReachable,
   UnsupportedCapabilityError,
+  UITooLargeError,
   RequenceUnreachableError,
   RequenceStream,
   RequenceFile,
@@ -2211,5 +2655,5 @@ export {
   PayloadTooLargeError
 };
 
-//# debugId=886A241C6AA974E564756E2164756E21
+//# debugId=D7A7D1B5373F4AAA64756E2164756E21
 //# sourceMappingURL=index.js.map