fix(framework): use explicit server result envelopes

Author: PatrickJS

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.11.7 - 2026-06-18
+
+- Introduced an explicit `__async_server_result__: 1` marker for framework
+  server-result envelopes so ordinary domain objects with fields such as
+  `value`, `signals`, `cache`, `html`, `boundary`, `redirect`, or `error`
+  remain application values.
+- Centralized server-result effect application and unwrapping across local
+  registry, remote proxy, and handler command paths so `.run(...)` and
+  namespaced calls return equivalent values without double-applying effects.
+- Kept cache-only and other effect-only server envelopes representable through
+  the explicit marker and updated server-call, router, partial, and SSR
+  examples to use the protocol.
+- Bundle size from bundled TypeScript source: `browser.ts` 183,176 B raw /
+  34,360 B gzip -> `browser.min.js` 77,854 B raw / 23,100 B gzip
+  (-105,322 B raw, -11,260 B gzip).
+
 ## 0.11.6 - 2026-06-18
 
 - Owned async-signal runs with private execution tokens so canceled, restored,

README.md

@@ -806,6 +806,7 @@ import {
 const server = createServerRegistry({
   "cart.add"(productId, quantity) {
     return {
+      __async_server_result__: 1,
       value: { ok: true },
       signals: {
         cartCount: 3

browser.js

@@ -2379,9 +2379,10 @@ const __componentModule = (() => {
 })();
 
 const __serverModule = (() => {
-  const serverEnvelopeKeys = new Set(["value", "signals", "boundary", "html", "redirect", "error"]);
+  const serverEnvelopeKind = Symbol.for("@async/framework.serverResult");
+  const serverEnvelopeWireKey = "__async_server_result__";
+  const serverEnvelopeWireVersion = 1;
   const appliedServerResult = Symbol.for("@async/framework.appliedServerResult");
-  const appliedServerValues = new WeakSet();
 
   function createServerProxy({
     endpoint = "/__async/server",
@@ -2424,9 +2425,7 @@ const __serverModule = (() => {
         throw new Error(`Server function "${id}" failed with ${response.status}.`);
       }
 
-      const result = await readServerResponse(id, response);
-      await applyServerResult(result, runContext);
-      return markAppliedServerValue(unwrapServerResult(result));
+      return consumeServerResult(await readServerResponse(id, response), runContext);
     }
 
     return createServerNamespace(run, {
@@ -2461,7 +2460,7 @@ const __serverModule = (() => {
     if (!isServerEnvelope(result)) {
       return result;
     }
-    if (result[appliedServerResult] || appliedServerValues.has(result)) {
+    if (result[appliedServerResult]) {
       return result;
     }
 
@@ -2493,18 +2492,16 @@ const __serverModule = (() => {
     return result;
   }
 
-  function unwrapServerResult(result) {
-    if (isServerEnvelope(result) && Object.hasOwn(result, "value")) {
-      return result.value;
-    }
-    return result;
+  async function consumeServerResult(result, context = {}) {
+    await applyServerResult(result, context);
+    return unwrapServerResult(result);
   }
 
-  function markAppliedServerValue(value) {
-    if (value && typeof value === "object") {
-      appliedServerValues.add(value);
+  function unwrapServerResult(result) {
+    if (isServerEnvelope(result)) {
+      return Object.hasOwn(result, "value") ? result.value : undefined;
     }
-    return value;
+    return result;
   }
 
   function markAppliedServerResult(result) {
@@ -2548,9 +2545,7 @@ const __serverModule = (() => {
           throw new Error("Server namespace is not directly callable.");
         }
         const context = contextProvider() ?? {};
-        const result = await run(parts.join("."), args, context);
-        await applyServerResult(result, context);
-        return unwrapServerResult(result);
+        return run(parts.join("."), args, context);
       };
 
       const proxy = new Proxy(callable, {
@@ -2607,7 +2602,7 @@ const __serverModule = (() => {
 
   async function readServerResponse(id, response) {
     if (response.status === 204) {
-      return { value: undefined };
+      return undefined;
     }
     const type = response.headers.get("content-type") ?? "";
     if (type.includes("application/json")) {
@@ -2625,7 +2620,7 @@ const __serverModule = (() => {
     if (typeof response.text !== "function") {
       throw new Error(`Server function "${id}" transport returned an invalid response: missing text().`);
     }
-    return { value: await response.text() };
+    return response.text();
   }
 
   function snapshotSignalPaths(paths = [], signals) {
@@ -2770,7 +2765,8 @@ const __serverModule = (() => {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
       return false;
     }
-    return Object.keys(value).some((key) => serverEnvelopeKeys.has(key));
+    return value[serverEnvelopeKind] === true
+      || value[serverEnvelopeWireKey] === serverEnvelopeWireVersion;
   }
 
   function toError(value) {
@@ -2792,11 +2788,11 @@ const __serverModule = (() => {
       throw new TypeError("Server function id must be a non-empty string.");
     }
   }
-  return { createServerProxy, resolveServerCommandArguments, applyServerResult, unwrapServerResult, defaultInput, createServerNamespace, createSignalReader, assertServerId };
+  return { createServerProxy, resolveServerCommandArguments, applyServerResult, consumeServerResult, unwrapServerResult, defaultInput, createServerNamespace, createSignalReader, assertServerId };
 })();
 
 const __handlersModule = (() => {
-  const { applyServerResult, defaultInput, resolveServerCommandArguments, unwrapServerResult } = __serverModule;
+  const { defaultInput, resolveServerCommandArguments } = __serverModule;
   const { attachRegistryInspection, createRegistryStore } = __registryStoreModule;
   const { createLazyRegistry, isLazyDescriptor } = __lazyRegistryModule;
   const builtInTokens = new Set(["prevent", "preventDefault", "stopPropagation", "stopImmediatePropagation"]);
@@ -2894,8 +2890,7 @@ const __handlersModule = (() => {
               signalPaths: resolved.signalPaths,
               signalValues: resolved.signalValues
             });
-            await applyServerResult(result, runContext);
-            results.push(unwrapServerResult(result));
+            results.push(result);
             continue;
           }