@lensmcp/valtio-instrumentation 1.23.13 → 1.24.0

package/README.md

@@ -48,6 +48,8 @@ const cart = proxy(
 );
 ```
 
+`emitInitialPreview` is **off by default**: a store's initial state is usually the whole application state, so `store-created` carries it only for stores that opt in. Every preview — the initial one and the one on each `state-update` — is small by construction: at most 3 levels deep (deeper containers read `[Object]` / `[Array(n)]`), 20 entries per level (`"…": "+N more keys"` / `"… N more items"`), 256 characters per string, and 4 KiB in all. The walk reads only what it keeps, so a store holding ten thousand records costs twenty reads, not ten thousand. Credentials inside a preview are redacted when the event reaches the lens.
+
 For cases where you want to declare a read path explicitly rather than infer it, use `useTrackedSnapshot`:
 
 ```ts
@@ -72,7 +74,7 @@ const snap = useTrackedSnapshot(cart, { storeId: 'cart', path: 'items' });
 | `unstable_enableOp` | Re-exported from `valtio/vanilla`. |
 | `unstable_getInternalStates` | Re-exported from `valtio/vanilla`. |
 | `unstable_replaceInternalFunction` | Re-exported from `valtio/vanilla`. |
-| `LensmcpProxyOptions` | Options for `proxy()`: `storeId?`, `source?`, `emitInitialPreview?`. |
+| `LensmcpProxyOptions` | Options for `proxy()`: `storeId?`, `source?`, `emitInitialPreview?` (default `false`). |
 | `UseSnapshotOptions` | Options for `useTrackedSnapshot()`: `storeId` (required), `path?`. |
 
 > `proxy` and `useSnapshot` are the instrumented versions; everything else passes through from the real Valtio (imported via the `valtio/vanilla` subpath so this module never aliases itself).

package/lib/preview.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Small previews of application state — the `preview` on a `state-update` and the opt-in
+ * `initialPreview` on a `store-created` (issues/closed/codex-security-43).
+ *
+ * WHY NOT `boundedClone`: that walk exists to protect a REDUCER, so it keeps every entry under
+ * 512 B "unconditionally, budget or not" — the rule that guarantees `raw.kind` and every small
+ * identifier survive a clamp. A preview has no discriminators to protect, and the most common store
+ * shape is exactly the one that rule lets through whole: a normalised entity map, thousands of small
+ * records. Measured: a 10 000-customer `users` map produced a 735 KB preview with every record in it,
+ * reported as `truncated: false`, against a 32 KiB budget. Its slow path also walks the WHOLE value
+ * once more to report `originalBytes` — on the browser's main thread, per mutated leaf.
+ *
+ * HERE every bound is hard and the walk costs what it keeps, not what the value holds:
+ *   - containers deeper than `maxDepth` become a summary (`[Object]`, `[Array(120)]`) — never entered,
+ *   - at most `maxEntries` entries per object/array are READ; the rest are counted, not visited,
+ *   - strings (and keys) are clipped to `maxStringChars`,
+ *   - the whole preview fits `maxBytes` of (approximate) JSON, overflow markers included.
+ *
+ * Counting an object's keys is the one cost proportional to the value, and it is paid only for a
+ * container the preview actually opens: a key list, no values read.
+ *
+ * Redaction is NOT done here: the bus redactor (`@lensmcp/core` `createEventRedactor`) covers every
+ * event at ingest. This walk only removes and clips, and keeps every kept key verbatim, so a
+ * credential the preview keeps is still one the bus redactor can name.
+ */
+export interface PreviewLimits {
+    /** Approximate serialized bytes the whole preview may take. Below {@link MIN_VALUE_BYTES} ⇒ no preview. */
+    maxBytes: number;
+    /** Container levels opened, the root included. A container below them becomes a summary. */
+    maxDepth: number;
+    /** Entries read per object or array; the rest are summarised by count. */
+    maxEntries: number;
+    /** Characters kept per string value and per key. */
+    maxStringChars: number;
+}
+/**
+ * Defaults: three levels — the depth `LENSMCP_VALTIO_PATH_DEPTH` reports read paths at — twenty
+ * entries a level, and 4 KiB in all, the same ceiling one subscription aggregate is held to.
+ */
+export declare const DEFAULT_PREVIEW_LIMITS: PreviewLimits;
+/**
+ * A bounded, JSON-safe preview of `value`, or `undefined` when the budget leaves no room for one.
+ * Never throws for a value that is merely large or deep; a getter that throws propagates.
+ */
+export declare function previewValue(value: unknown, limits?: PreviewLimits): unknown;

package/lib/preview.js

@@ -0,0 +1 @@
+"use strict";var A=Object.defineProperty;var n=(t,e)=>A(t,"name",{value:e,configurable:!0});var E=Object.defineProperty,l=n((t,e)=>E(t,"name",{value:e,configurable:!0}),"s");export const DEFAULT_PREVIEW_LIMITS={maxBytes:4096,maxDepth:3,maxEntries:20,maxStringChars:256};const a=32,d=32,O=2+a+d;export function previewValue(t,e=DEFAULT_PREVIEW_LIMITS){if(!(e.maxBytes>=a))return;const u={limits:e,budget:e.maxBytes};return m(t,u,1,0)}n(previewValue,"previewValue"),l(previewValue,"previewValue");function m(t,e,u,i){switch(typeof t){case"string":return f(t,Math.min(e.limits.maxStringChars,e.budget-i-2),e);case"number":return o(e,Number.isFinite(t)?t:null);case"boolean":return o(e,t);case"bigint":return f(t.toString(),a-2,e);case"undefined":case"function":case"symbol":return;default:break}if(t===null)return o(e,null);if(t instanceof Date)return Number.isNaN(t.getTime())?o(e,null):f(t.toISOString(),a-2,e);if(ArrayBuffer.isView(t))return c(e,`[${Object.prototype.toString.call(t).slice(8,-1)}(${t.byteLength} B)]`);const r=u<=e.limits.maxDepth&&e.budget-i>=O;return Array.isArray(t)?r?S(t,e,u,i):c(e,`[Array(${t.length})]`):r?v(t,e,u,i):c(e,"[Object]")}n(m,"l"),l(m,"previewOf");function S(t,e,u,i){const r=[];e.budget-=2;const g=i+d,h=Math.min(t.length,e.limits.maxEntries);for(let s=0;s<h&&!(e.budget-g-1<a);s++){e.budget-=1;const b=m(t[s],e,u+1,g);r.push(b===void 0?o(e,null):b)}return r.length<t.length&&r.push(c(e,`\u2026 ${t.length-r.length} more items`)),r}n(S,"k"),l(S,"previewArray");function v(t,e,u,i){const r={};e.budget-=2;const g=i+d,h=Object.keys(t);let s=0;for(const b of h){if(s>=e.limits.maxEntries)break;const p=$(b,e.limits.maxStringChars),y=p.length+4;if(e.budget-g-y<a)break;const w=e.budget;e.budget-=y;const x=m(t[b],e,u+1,g);x===void 0?e.budget=w:r[p]=x,s+=1}return s<h.length&&(e.budget-=5,r["\u2026"]=c(e,`+${h.length-s} more keys`)),r}n(v,"A"),l(v,"previewObject");function o(t,e){return t.budget-=e===null?4:String(e).length,e}n(o,"b"),l(o,"spend");function c(t,e){return t.budget-=e.length+2,e}n(c,"d"),l(c,"summary");function f(t,e,u){let i=t;if(t.length>e){const r=Math.max(0,Math.floor(e)-11-String(t.length).length);i=`${t.slice(0,r)}\u2026 (+${t.length-r} chars)`}return u.budget-=i.length+2,i}n(f,"a"),l(f,"clipString");function $(t,e){return t.length<=e?t:`${t.slice(0,e)}\u2026`}n($,"M"),l($,"clipKey");

package/lib/proxy.d.ts

@@ -3,7 +3,11 @@ export interface LensmcpProxyOptions {
     storeId?: string;
     /** Source path (file:line) the proxy was created at. */
     source?: string;
-    /** Include first-level state in `store-created` events. */
+    /**
+     * Include a bounded preview of the initial state in the `store-created` event. Off by default: the
+     * initial store is typically the whole application state, and what `valtio://stores` returned to
+     * any MCP client (issues/closed/codex-security-43). Opt in per store.
+     */
     emitInitialPreview?: boolean;
 }
 /**

package/lib/proxy.js

@@ -1 +1 @@
-"use strict";var y=Object.defineProperty;var o=(e,t)=>y(e,"name",{value:t,configurable:!0});var h=Object.defineProperty,n=o((e,t)=>h(e,"name",{value:t,configurable:!0}),"n");import{proxy as g,subscribe as P,unstable_enableOp as w}from"valtio/vanilla";import{publish as $,publishLazy as I,depsHash as f}from"@lensmcp/react-instrumentation";import{boundedClone as x}from"@lensmcp/protocol-types";import{registerStore as E,subscribersForPathAndParents as S,tagProxy as L}from"./store-registry.js";import{truncatePath as _}from"./snapshot.js";let l=!1;function d(){if(!l)try{w(!0),l=!0}catch{}}o(d,"I"),n(d,"ensureOpsEnabled");let O=0;export function proxy(e,t={}){d();const r=t.storeId??`valtio:store:${++O}`;E(r,t.source);const a=g(e);return L(a,r),$({source:"valtio",category:"state",severity:"info",title:`store-created ${r}`,fingerprint:`valtio-store:${r}`,raw:{kind:"store-created",store:{storeId:r,source:t.source,initialPreview:t.emitInitialPreview===!1?void 0:c(e)}}}),P(a,v=>{for(const b of v){const[,s,u,m]=b;if(!(s??[]).length)continue;const p=`valtio-update:${r}:${_(s??[])}`;I(p,()=>{const i=(s??[]).map(String).join(".");return{source:"valtio",category:"state",severity:"info",title:`state-update ${r}.${i}`,fingerprint:p,raw:{kind:"state-update",update:{storeId:r,path:i,changedKeys:(s??[]).map(String),beforeHash:f([m]),afterHash:f([u]),preview:c(u),subscribers:S(r,i)}}}})}},!0),a}o(proxy,"proxy"),n(proxy,"proxy");const H=(()=>{const e=typeof process<"u"?process.env?.LENSMCP_VALTIO_PREVIEW_BYTES:void 0,t=Number(e);return Number.isFinite(t)&&t>=0?Math.floor(t):32*1024})();function c(e){try{return x(e,{rawByteLimit:H}).value}catch{return}}o(c,"f"),n(c,"safePreview");
+"use strict";var h=Object.defineProperty;var s=(e,t)=>h(e,"name",{value:t,configurable:!0});var g=Object.defineProperty,n=s((e,t)=>g(e,"name",{value:t,configurable:!0}),"s");import{proxy as P,subscribe as I,unstable_enableOp as E}from"valtio/vanilla";import{publish as w,publishLazy as x,depsHash as f}from"@lensmcp/react-instrumentation";import{DEFAULT_PREVIEW_LIMITS as l,previewValue as $}from"./preview.js";import{registerStore as S,subscribersForPathAndParents as _,tagProxy as L}from"./store-registry.js";import{truncatePath as V}from"./snapshot.js";let d=!1;function v(){if(!d)try{E(!0),d=!0}catch{}}s(v,"$"),n(v,"ensureOpsEnabled");let O=0;export function proxy(e,t={}){v();const r=t.storeId??`valtio:store:${++O}`;S(r,t.source);const a=P(e);return L(a,r),w({source:"valtio",category:"state",severity:"info",title:`store-created ${r}`,fingerprint:`valtio-store:${r}`,raw:{kind:"store-created",store:{storeId:r,source:t.source,initialPreview:t.emitInitialPreview===!0?c(e):void 0}}}),I(a,m=>{for(const b of m){const[,o,u,y]=b;if(!(o??[]).length)continue;const p=`valtio-update:${r}:${V(o??[])}`;x(p,()=>{const i=(o??[]).map(String).join(".");return{source:"valtio",category:"state",severity:"info",title:`state-update ${r}.${i}`,fingerprint:p,raw:{kind:"state-update",update:{storeId:r,path:i,changedKeys:(o??[]).map(String),beforeHash:f([y]),afterHash:f([u]),preview:c(u),subscribers:_(r,i)}}}})}},!0),a}s(proxy,"proxy"),n(proxy,"proxy");const T=(()=>{const e=typeof process<"u"?process.env?.LENSMCP_VALTIO_PREVIEW_BYTES:void 0,t=Number(e),r=e!==void 0&&e!==""&&Number.isFinite(t)&&t>=0;return{...l,maxBytes:r?Math.floor(t):l.maxBytes}})();function c(e){try{return $(e,T)}catch{return}}s(c,"d"),n(c,"safePreview");

package/lib/types.d.ts

@@ -20,7 +20,7 @@ export interface ValtioStoreRecord {
 /**
  * One commit's worth of subscription changes for one hook instance — NOT one path.
  *
- * issues/codex-security/58: this used to be one event per path, so a component reading N entries of a
+ * issues/closed/codex-security-58: this used to be one event per path, so a component reading N entries of a
  * large collection published O(N) events per commit and another O(N) on unmount. `paths` carries the
  * whole delta in a single event; `path` is `paths[0]`, kept so a consumer written against the old
  * one-path-per-event shape still keys on a real path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/valtio-instrumentation",
-  "version": "1.23.13",
+  "version": "1.24.0",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",
@@ -14,8 +14,8 @@
     }
   },
   "dependencies": {
-    "@lensmcp/protocol-types": "1.23.13",
-    "@lensmcp/react-instrumentation": "1.23.13",
+    "@lensmcp/protocol-types": "1.24.0",
+    "@lensmcp/react-instrumentation": "1.24.0",
     "proxy-compare": "^3.0.0",
     "tslib": "^2.3.0"
   },