@webjsdev/core 0.7.18 → 0.7.20

package/index-browser.js

@@ -3,7 +3,7 @@
  *
  * Mirror of `./index.js` but with strictly server-only exports
  * removed so the browser bundle never drags `src/render-server.js`
- * (~1100 lines) or `src/expose.js` (~90 lines) over the wire.
+ * (~1100 lines) over the wire.
  *
  * Stripped:
  *   - `renderToString`, `renderToStream` (server SSR pipeline; reach
@@ -11,10 +11,6 @@
  *   - `setCspNonceProvider` (server-side wiring called by
  *     `@webjsdev/server`'s context module; `cspNonce()` stays
  *     because layouts can call it).
- *   - `expose`, `getExposed` (live inside `.server.{js,ts}` files;
- *     framework rewrites the import to an RPC stub on the client
- *     side, so the real module never legitimately reaches the
- *     browser).
  *
  * The framework's own SSR pipeline runs on Node and resolves the
  * package via the package.json `"default"` condition, which still
@@ -55,6 +51,16 @@ export { optimistic } from './src/optimistic.js';
 // SSR action-seed consumer (#472): the generated RPC stub reads a seed on its
 // first call so async-render hydration does not re-fetch the SSR'd data.
 export { takeSeed, scanSeeds, SEED_MISS } from './src/action-seed-client.js';
+// Client tag-cache coordinator for HTTP-verb actions (#488): tag-based
+// browser-cache eviction after a mutation. Inert server-side.
+export { markStale, registerKeyTags, consumeStale, parseTagHeader, fetchMark } from './src/action-cache-client.js';
+// Client action-abort plumbing (#492): a superseded async render aborts its
+// in-flight action fetches. Inert server-side.
+export { setActiveActionSignal, activeActionSignal } from './src/action-abort-client.js';
+// Streaming RPC wire protocol (#489): the byte framing the client stub decodes.
+export {
+  STREAM_CONTENT_TYPE, FRAME_CHUNK, FRAME_END, FRAME_ERROR, encodeFrame, createFrameDecoder,
+} from './src/action-stream.js';
 
 // Directives, also available via '@webjsdev/core/directives'. The full
 // lit-html-parity set is re-exported here so the dist browser bundle (which

package/index.d.ts

@@ -54,6 +54,16 @@ export type {
   WebjsCspConfig,
 } from './src/webjs-config.d.ts';
 
+// Compile-time serializability typing for server actions (#488): the opt-in
+// guard that makes a non-serializable action arg / return a type error.
+export type {
+  Serializable,
+  SerializableArgs,
+  SerializableResult,
+  SerializableActionFn,
+  NonSerializable,
+} from './src/serializable.d.ts';
+
 export { html, isTemplate, MARKER } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
 export { register, lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
@@ -61,7 +71,6 @@ export { renderToString, renderToStream } from './src/render-server.js';
 export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, isNotFound, isRedirect } from './src/nav.js';
-export { expose, getExposed, validateInput } from './src/expose.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';
@@ -92,6 +101,14 @@ export { Task, TaskStatus } from './src/task.js';
 export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
 export { cspNonce, setCspNonceProvider } from './src/csp-nonce.js';
 export { takeSeed, scanSeeds, SEED_MISS } from './src/action-seed-client.js';
+export { markStale, registerKeyTags, consumeStale, parseTagHeader, fetchMark } from './src/action-cache-client.js';
+// Client action-abort plumbing (#492): a superseded async render aborts its
+// in-flight action fetches. Inert server-side.
+export { setActiveActionSignal, activeActionSignal } from './src/action-abort-client.js';
+// Streaming RPC wire protocol (#489).
+export {
+  STREAM_CONTENT_TYPE, FRAME_CHUNK, FRAME_END, FRAME_ERROR, encodeFrame, createFrameDecoder,
+} from './src/action-stream.js';
 export { stringify, parse, serialize, deserialize } from './src/serialize.js';
 export { WebjsFrame } from './src/webjs-frame.js';
 export { WebjsStream, renderStream } from './src/webjs-stream.js';

package/index.js

@@ -15,7 +15,6 @@ export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, isNotFound, isRedirect } from './src/nav.js';
 export { cspNonce, setCspNonceProvider } from './src/csp-nonce.js';
-export { expose, getExposed, validateInput } from './src/expose.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';
@@ -37,6 +36,17 @@ export { optimistic } from './src/optimistic.js';
 // SSR action-seed consumer (#472): the generated RPC stub reads a seed on its
 // first call so async-render hydration does not re-fetch. Inert server-side.
 export { takeSeed, scanSeeds, SEED_MISS } from './src/action-seed-client.js';
+// Client tag-cache coordinator for HTTP-verb actions (#488): tag-based
+// browser-cache eviction after a mutation. Inert server-side.
+export { markStale, registerKeyTags, consumeStale, parseTagHeader, fetchMark } from './src/action-cache-client.js';
+// Client action-abort plumbing (#492): a superseded async render aborts its
+// in-flight action fetches. Inert server-side.
+export { setActiveActionSignal, activeActionSignal } from './src/action-abort-client.js';
+// Streaming RPC wire protocol (#489): the byte framing the server encodes a
+// streamed action result with and the client stub decodes. Pure byte ops.
+export {
+  STREAM_CONTENT_TYPE, FRAME_CHUNK, FRAME_END, FRAME_ERROR, encodeFrame, createFrameDecoder,
+} from './src/action-stream.js';
 
 // Directives, also available via '@webjsdev/core/directives'. The full
 // lit-html-parity set is re-exported so the bare specifier exposes the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.18",
+  "version": "0.7.20",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/action-abort-client.d.ts

@@ -0,0 +1,3 @@
+/** Client action-abort plumbing (#492). Inert server-side. */
+export function setActiveActionSignal(signal: AbortSignal | null): void;
+export function activeActionSignal(): AbortSignal | undefined;

package/src/action-abort-client.js

@@ -0,0 +1,39 @@
+/**
+ * Client-side action abort plumbing (#492).
+ *
+ * An `async render()` that supersedes an in-flight one should ABORT the previous
+ * render's action fetches, not just drop their results. The component sets a
+ * fresh AbortController's signal as the "active" signal right before each render
+ * (`setActiveActionSignal`), and the generated RPC stub binds every `fetch` to
+ * `activeActionSignal()`. When the next render supersedes, the component aborts
+ * the previous controller, cancelling those fetches.
+ *
+ * Best-effort by design: the stub reads the active signal SYNCHRONOUSLY when the
+ * action is called, so it binds for an action invoked in the synchronous portion
+ * of `render()` (the common `const u = await getUser(id)` first statement). An
+ * action invoked after a later `await` may see no active signal; it then simply
+ * runs to completion and its result is dropped by the existing render-token
+ * guard, exactly as before this feature. Inert server-side (never set there).
+ */
+
+/** The AbortSignal the currently-rendering component bound, or null. */
+let active = null;
+
+/**
+ * Set (or clear with null) the signal the generated RPC stub binds its fetches
+ * to. The component sets this around the synchronous portion of `render()`.
+ * @param {AbortSignal | null} signal
+ */
+export function setActiveActionSignal(signal) {
+  active = signal || null;
+}
+
+/**
+ * The active abort signal a stub should bind a fetch to, or undefined when no
+ * render is in flight (an action called from an event handler is not bound, so
+ * a re-render never aborts a user-triggered mutation).
+ * @returns {AbortSignal | undefined}
+ */
+export function activeActionSignal() {
+  return active || undefined;
+}

package/src/action-cache-client.d.ts

@@ -0,0 +1,6 @@
+/** Client tag-cache coordinator for HTTP-verb server actions (#488). Inert server-side. */
+export function markStale(tags: string[]): void;
+export function fetchMark(): number;
+export function registerKeyTags(key: string, tags: string[], since?: number): void;
+export function consumeStale(key: string): boolean;
+export function parseTagHeader(value: string | null): string[];

package/src/action-cache-client.js

@@ -0,0 +1,103 @@
+/**
+ * Client-side tag cache coordinator for HTTP-verb server actions (#488).
+ *
+ * A GET action is cached by the BROWSER HTTP cache (its `Cache-Control` +
+ * ETag). After a mutation, that cached entry would still be served within its
+ * `max-age`, so a tag-based eviction is layered on top: the server tells the
+ * client which tags a GET belongs to (the `X-Webjs-Tags` response header) and
+ * which tags a mutation invalidated (`X-Webjs-Invalidate`). When a later GET's
+ * tags were invalidated AFTER that key's last fetch STARTED, the stub re-fetches
+ * with `cache: 'no-cache'` (a conditional revalidation that bypasses the stale
+ * browser-cache entry and returns fresh data, since the ETag changed).
+ *
+ * Mechanism: a monotonic CLOCK, bumped on every invalidation. Each tag records
+ * the clock at its last invalidation; each GET records the clock value SAMPLED
+ * JUST BEFORE its fetch was dispatched. A read needs a bypass when any of its
+ * tags was invalidated at a clock value greater than the key's sampled value.
+ * Sampling before the fetch (not when the response lands) is what closes the
+ * race where a mutation commits while a read is in flight: such a mutation has
+ * a higher clock than the read's sample, so the next read still bypasses.
+ *
+ * A thin coordinator, NOT a data store (the data lives in the browser HTTP
+ * cache, on-thesis: no bespoke client query cache). Inert server-side.
+ */
+
+/** Monotonic logical clock; bumped once per `markStale` call. */
+let clock = 0;
+
+/** `tag -> clock value at its last invalidation`. */
+const tagInvalidatedAt = new Map();
+
+/** `key -> { tags, since }` where `since` is the clock sampled before its fetch. */
+const keyInfo = new Map();
+
+/** Bound `keyInfo` growth for a long-lived session (FIFO-evict the oldest). */
+const MAX_KEYS = 1000;
+
+/**
+ * Mark tags invalidated (called after a mutation reports `X-Webjs-Invalidate`):
+ * advance the clock and stamp each tag with it.
+ * @param {string[]} tags
+ */
+export function markStale(tags) {
+  if (!Array.isArray(tags) || !tags.length) return;
+  clock += 1;
+  for (const t of tags) if (t) tagInvalidatedAt.set(t, clock);
+}
+
+/**
+ * Sample the clock just before dispatching a GET fetch. The value is passed to
+ * `registerKeyTags` so an invalidation that lands WHILE the fetch is in flight
+ * (a higher clock than this sample) is detected on the next read.
+ * @returns {number}
+ */
+export function fetchMark() {
+  return clock;
+}
+
+/**
+ * Record the tags a GET response declared for its key, stamped with the clock
+ * value sampled before the fetch (`since`).
+ * @param {string} key the GET cache key (`stringify(args)`)
+ * @param {string[]} tags
+ * @param {number} [since] the `fetchMark()` sampled before the fetch
+ */
+export function registerKeyTags(key, tags, since) {
+  if (!Array.isArray(tags) || !tags.length) return;
+  // Re-insert to move the key to the newest position (LRU-ish), then cap.
+  keyInfo.delete(key);
+  keyInfo.set(key, { tags: tags.slice(), since: typeof since === 'number' ? since : clock });
+  if (keyInfo.size > MAX_KEYS) {
+    const oldest = keyInfo.keys().next().value;
+    if (oldest !== undefined) keyInfo.delete(oldest);
+  }
+}
+
+/**
+ * Whether a GET for `key` should bypass the browser cache (re-fetch with
+ * `cache: 'no-cache'`) because one of its tags was invalidated AFTER this key's
+ * last fetch started. An unrecorded key (never fetched, e.g. resolved from the
+ * SSR seed) returns false: its browser-cache entry does not exist yet, so a
+ * normal fetch already returns fresh data.
+ * @param {string} key
+ * @returns {boolean}
+ */
+export function consumeStale(key) {
+  const info = keyInfo.get(key);
+  if (!info) return false;
+  for (const t of info.tags) if ((tagInvalidatedAt.get(t) || 0) > info.since) return true;
+  return false;
+}
+
+/** Parse a comma-separated tag header into a trimmed, non-empty list. */
+export function parseTagHeader(value) {
+  if (!value) return [];
+  return value.split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+/** Test seam: clear all tag state. */
+export function __resetActionCache() {
+  clock = 0;
+  tagInvalidatedAt.clear();
+  keyInfo.clear();
+}

package/src/action-stream.d.ts

@@ -0,0 +1,12 @@
+/** Streaming RPC wire protocol (#489). See action-stream.js. */
+
+export declare const STREAM_CONTENT_TYPE: string;
+export declare const FRAME_CHUNK: number;
+export declare const FRAME_END: number;
+export declare const FRAME_ERROR: number;
+
+export declare function encodeFrame(type: number, payload?: Uint8Array): Uint8Array;
+
+export declare function createFrameDecoder(): {
+  push(chunk: Uint8Array): Array<{ type: number; payload: Uint8Array }>;
+};

package/src/action-stream.js

@@ -0,0 +1,92 @@
+/**
+ * Streaming RPC wire protocol (#489), shared by the server (which frames an
+ * action's streamed result) and the client RPC stub (which decodes it). It lives
+ * in core because both sides need the EXACT same byte format; the server imports
+ * `encodeFrame` and the stub imports `createFrameDecoder` from `@webjsdev/core`.
+ *
+ * An action that returns a `ReadableStream` / async iterable / async generator
+ * streams its chunks over a single RPC response (one fetch, not multiplexed, so
+ * no stream-id is needed). The response carries `STREAM_CONTENT_TYPE`, and its
+ * body is a sequence of length-prefixed frames:
+ *
+ *   ┌────────┬──────────────┬──────────────────────┐
+ *   │ type:1 │  length:4 BE │  payload: length bytes│
+ *   └────────┴──────────────┴──────────────────────┘
+ *
+ *   - CHUNK (1): payload is one serialized chunk value (the same wire format the
+ *     RPC envelope uses, so a rich value round-trips). The client deserializes it
+ *     and yields it from the async iterable the stub returns.
+ *   - END   (2): length 0, no payload. Clean completion; the iterable returns.
+ *   - ERROR (3): payload is the (author-controlled) error message string. The
+ *     stream errored after the first byte, so it cannot change the HTTP status;
+ *     the client throws this message from the iterable instead.
+ *
+ * Pure byte manipulation, no DOM and no `node:*` deps, so it is safe in the
+ * browser bundle and on the server alike.
+ */
+
+/** The RPC content type for a framed streamed result. */
+export const STREAM_CONTENT_TYPE = 'application/vnd.webjs+stream';
+
+/** Frame type: one serialized chunk value. */
+export const FRAME_CHUNK = 1;
+/** Frame type: clean end of stream (empty payload). */
+export const FRAME_END = 2;
+/** Frame type: the stream errored mid-flight (payload is the message). */
+export const FRAME_ERROR = 3;
+
+const EMPTY = new Uint8Array(0);
+
+/**
+ * Frame a payload as `[type:1][length:4 BE][payload]`. `payload` may be omitted
+ * for a zero-length frame (END).
+ * @param {number} type one of FRAME_CHUNK / FRAME_END / FRAME_ERROR
+ * @param {Uint8Array} [payload]
+ * @returns {Uint8Array}
+ */
+export function encodeFrame(type, payload) {
+  const body = payload || EMPTY;
+  const len = body.length;
+  const out = new Uint8Array(5 + len);
+  out[0] = type & 0xff;
+  out[1] = (len >>> 24) & 0xff;
+  out[2] = (len >>> 16) & 0xff;
+  out[3] = (len >>> 8) & 0xff;
+  out[4] = len & 0xff;
+  if (len) out.set(body, 5);
+  return out;
+}
+
+/**
+ * A stateful decoder that turns a stream of arbitrary byte chunks back into
+ * whole frames, buffering across chunk boundaries (a frame may be split over two
+ * network reads, or two frames may arrive in one read). `push(chunk)` returns the
+ * array of complete frames it could parse from the accumulated buffer so far;
+ * partial trailing bytes stay buffered for the next `push`.
+ * @returns {{ push(chunk: Uint8Array): Array<{ type: number, payload: Uint8Array }> }}
+ */
+export function createFrameDecoder() {
+  let buf = EMPTY;
+  return {
+    push(chunk) {
+      if (chunk && chunk.length) {
+        const next = new Uint8Array(buf.length + chunk.length);
+        next.set(buf, 0);
+        next.set(chunk, buf.length);
+        buf = next;
+      }
+      const frames = [];
+      // A frame needs at least the 5-byte header before its length is known.
+      while (buf.length >= 5) {
+        const type = buf[0];
+        const len = ((buf[1] << 24) | (buf[2] << 16) | (buf[3] << 8) | buf[4]) >>> 0;
+        if (buf.length < 5 + len) break; // payload not fully arrived yet
+        // Copy the payload out so it does not alias the (soon-reassigned) buffer.
+        const payload = buf.slice(5, 5 + len);
+        frames.push({ type, payload });
+        buf = buf.slice(5 + len);
+      }
+      return frames;
+    },
+  };
+}

package/src/component.js

@@ -1,4 +1,5 @@
 import { render as clientRender } from './render-client.js';
+import { setActiveActionSignal } from './action-abort-client.js';
 import { isCSS, adoptStyles } from './css.js';
 import { register, tagOf } from './registry.js';
 import { parse as deserializeProp } from './serialize.js';
@@ -1015,11 +1016,23 @@ export class WebComponent extends Base {
         // by-sync case (#469); a shouldUpdate=false cycle never reaches here,
         // so it does not invalidate an in-flight async render.
         this.__renderToken = (this.__renderToken || 0) + 1;
+        // Abort the superseded render's in-flight action fetches (#492), start a
+        // fresh controller for this render, and bind it as the active signal so
+        // the RPC stub ties its fetches to this render. A superseded fetch's
+        // AbortError is dropped by the render-token guard in _commitAsync.
+        if (this.__renderAbort) this.__renderAbort.abort();
+        this.__renderAbort = typeof AbortController !== 'undefined' ? new AbortController() : null;
+        setActiveActionSignal(this.__renderAbort ? this.__renderAbort.signal : null);
         try {
           const r = this.update(changedProperties);
           if (r && typeof r.then === 'function') pendingCommit = r;
         } catch (error) {
           this._handleRenderError(/** @type {Error} */ (error));
+        } finally {
+          // The synchronous portion of render() has run; actions invoked there
+          // already captured the signal. Clear it so a later event handler is
+          // not bound to a stale render's controller.
+          setActiveActionSignal(null);
         }
 
         if (!pendingCommit) {

package/src/serializable.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Compile-time serializability typing for server actions (#488).
+ *
+ * A `'use server'` action's arguments and result cross the RPC wire through the
+ * webjs serializer, which round-trips a SPECIFIC set of rich types (`Date`,
+ * `Map`, `Set`, `BigInt`, `Error`, `RegExp`, `URL`, typed arrays, `ArrayBuffer`,
+ * `Blob`, `File`, `FormData`, registered `Symbol`s, plain objects / arrays, and
+ * cycles). It does NOT round-trip a FUNCTION or a class instance's METHODS: a
+ * function silently vanishes from the wire, and a class instance arrives as a
+ * plain object with its prototype (so its methods) gone. That is a runtime
+ * surprise the author never asked for.
+ *
+ * `Serializable<T>` makes it a TYPE error instead. It maps a fully serializable
+ * `T` to itself, and a `T` that carries a function (a method, a callback prop)
+ * to a branded `NonSerializable<...>` marker, so assigning the offending value
+ * fails to typecheck with a message that names the problem. `SerializableArgs`
+ * / `SerializableResult` apply it across an action's parameter tuple and its
+ * (possibly promised) return.
+ *
+ * This is OPT-IN by design: webjs actions stay plain `export async function`s
+ * with no wrapper (the framework rewrites the client import to an RPC stub at
+ * runtime, it does not wrap the authored function). An author who wants the
+ * guard annotates the action with `SerializableActionFn`, e.g.
+ *
+ *   import type { SerializableActionFn } from '@webjsdev/core';
+ *   export const getUser: SerializableActionFn<(id: number) => Promise<User>> =
+ *     async (id) => db.user.find(id);
+ *
+ * If `User` (or any arg) is not serializable, the annotation is a compile-time
+ * error pointing at the offending member. Types only, erased at runtime, zero
+ * cost.
+ */
+
+/** A branded marker a non-serializable position resolves to, so the error names it. */
+export type NonSerializable<Reason extends string = 'this value is not serializable over the webjs RPC wire'> = {
+  readonly __webjsNonSerializable: Reason;
+};
+
+/** Primitives the wire carries verbatim. */
+type SerializablePrimitive = string | number | boolean | bigint | null | undefined;
+
+/**
+ * Built-in rich types the webjs serializer round-trips as themselves (their
+ * identity / methods survive because the serializer reconstructs the instance).
+ * `Map` / `Set` recurse into their members via the top-level mapper.
+ */
+type SerializableBuiltin =
+  | Date
+  | RegExp
+  | URL
+  | Error
+  | ArrayBuffer
+  | Int8Array | Uint8Array | Uint8ClampedArray
+  | Int16Array | Uint16Array
+  | Int32Array | Uint32Array
+  | Float32Array | Float64Array
+  | BigInt64Array | BigUint64Array
+  | Blob
+  | File
+  | FormData;
+
+/**
+ * Map `T` to itself when it is fully serializable, else to a `NonSerializable`
+ * marker at the offending position. A function (a method or a callback-valued
+ * property) is the canonical non-serializable case. Objects and arrays recurse;
+ * `Map` / `Set` recurse into their type parameters.
+ */
+export type Serializable<T> =
+  T extends SerializablePrimitive ? T :
+  // A function never survives the wire (it just disappears).
+  T extends (...args: any[]) => any ? NonSerializable<'a function is not serializable over the webjs RPC wire'> :
+  T extends SerializableBuiltin ? T :
+  T extends Map<infer K, infer V> ? Map<Serializable<K>, Serializable<V>> :
+  T extends Set<infer U> ? Set<Serializable<U>> :
+  T extends Promise<infer U> ? Promise<Serializable<U>> :
+  T extends ReadonlyArray<infer U> ? (T extends Array<infer _W> ? Array<Serializable<U>> : ReadonlyArray<Serializable<U>>) :
+  T extends object ? { [K in keyof T]: Serializable<T[K]> } :
+  T;
+
+/** Apply {@link Serializable} across an action's parameter tuple. */
+export type SerializableArgs<A extends readonly unknown[]> = {
+  [K in keyof A]: Serializable<A[K]>;
+};
+
+/**
+ * Apply {@link Serializable} to an action's return, unwrapping a `Promise` so an
+ * async action is checked against its resolved value (the wire carries the
+ * resolved value, never the promise).
+ */
+export type SerializableResult<R> =
+  R extends Promise<infer U> ? Promise<Serializable<U>> : Serializable<R>;
+
+/**
+ * The opt-in annotation type for a server action: it preserves the function's
+ * exact call signature while constraining every argument and the result to be
+ * serializable. A non-serializable arg or return makes the annotation a
+ * compile-time error.
+ *
+ * @example
+ *   export const getUser: SerializableActionFn<(id: number) => Promise<User>> =
+ *     async (id) => db.user.find(id);
+ */
+export type SerializableActionFn<F extends (...args: any[]) => any> =
+  (...args: SerializableArgs<Parameters<F>>) => SerializableResult<ReturnType<F>>;

package/src/serialize.js

@@ -51,6 +51,36 @@
 const TAG = '_$wj';
 const ID_KEY = '_id';
 
+/**
+ * Keys that, assigned with bracket notation, mutate the target instead of
+ * adding an own data property: `out['__proto__'] = x` invokes the prototype
+ * setter (a prototype-pollution vector on decode, reachable because
+ * `JSON.parse` makes a wire `"__proto__"` an OWN key; and on encode it silently
+ * DROPS a legitimate own `__proto__` data property and corrupts the
+ * accumulator's prototype). `constructor` / `prototype` shadow in ways
+ * downstream code can be confused by.
+ */
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Assign `value` onto a plain accumulator under `key`. A normal key is a plain
+ * assignment (the hot path); an unsafe key is written as an ordinary own
+ * enumerable data property via `defineProperty`, so the value survives as data
+ * (round-trippable, since JSON includes an own enumerable `__proto__`) and the
+ * prototype chain is never touched. Used on BOTH the encode and decode object
+ * loops so `serialize` / `deserialize` stay inverses on these keys.
+ * @param {Record<string, unknown>} out
+ * @param {string} key
+ * @param {unknown} value
+ */
+function safeAssign(out, key, value) {
+  if (UNSAFE_KEYS.has(key)) {
+    Object.defineProperty(out, key, { value, writable: true, enumerable: true, configurable: true });
+  } else {
+    out[key] = value;
+  }
+}
+
 /* ----------------------------------------------------------------- *
  * Public API                                                        *
  * ----------------------------------------------------------------- */
@@ -225,7 +255,7 @@ function encodeOne(v, ctx) {
     for (const k in v) {
       if (!Object.prototype.hasOwnProperty.call(v, k)) continue;
       const escaped = isReservedKey(k) ? '_' + k : k;
-      out[escaped] = encodeOne(v[k], ctx);
+      safeAssign(out, escaped, encodeOne(v[k], ctx));
     }
   }
 
@@ -314,7 +344,7 @@ function decode(v, ctx) {
     if (!Object.prototype.hasOwnProperty.call(v, k)) continue;
     if (k === ID_KEY) continue;
     const realKey = isEscapedReservedKey(k) ? k.slice(1) : k;
-    out[realKey] = decode(v[k], ctx);
+    safeAssign(out, realKey, decode(v[k], ctx));
   }
   return out;
 }