@lownoise-studio/render-shield-react 0.3.0-alpha.1

package/README.md

@@ -0,0 +1,334 @@
+RenderShield React
+A verification layer for React render decisions.
+
+React can skip rerenders.
+
+But when it does — how do you verify what was actually prevented, and why?
+
+RenderShield React is a lightweight developer instrument that:
+
+Applies structured prop comparison
+
+Allows surgical deep-watching of specific nested paths
+
+Reports why a render was shielded or accepted
+
+It does not mutate props.
+It does not rewrite state.
+It does not guarantee performance gains.
+
+It exposes the decision boundary.
+
+It prefers doing nothing over doing the wrong thing.
+
+Why This Exists
+
+Many unnecessary rerenders originate from:
+
+Unstable object references
+
+Inline functions recreated each render
+
+Deep state updates unrelated to rendered output
+
+Parent rerender cascades
+
+AI-generated components that leak references
+
+Blindly applying React.memo, useMemo, or useCallback can obscure the underlying cause.
+
+RenderShield React is not a magic fix.
+
+It is a visibility instrument.
+
+It helps you answer:
+
+Did this render actually need to happen?
+
+Which keys changed?
+
+Were watched paths stable?
+
+Was shielding correct?
+
+You don’t guess.
+
+You verify.
+
+Installation
+npm install @lownoise-studio/render-shield-react
+
+Core Hook
+useRenderShield(
+  value: T,
+  options?: {
+    watch?: string[];
+    debug?: boolean;
+    visual?: boolean;
+    customCompare?: (prev: T, next: T) => boolean;
+    componentName?: string;
+  }
+)
+
+Default Behavior (Shallow Comparison)
+
+By default, the hook performs a shallow comparison of top-level keys.
+
+If no top-level keys changed → previous reference is returned.
+
+If any top-level key changed → new value is accepted.
+
+No mutation occurs.
+
+Original references are preserved.
+
+Shallow comparison remains O(n) where n is the number of top-level keys.
+
+No hidden recursion.
+
+Watch Paths (Targeted Deep Comparison)
+
+You may provide specific nested paths to compare:
+
+const shieldedProps = useRenderShield(props, {
+  watch: ["user.id"]
+});
+
+
+When watch is provided:
+
+Only those paths are deep-compared.
+
+No full-object recursion occurs.
+
+If watched paths are stable, shielding may occur even if unrelated keys changed.
+
+If a watched path changes, shielding is disabled.
+
+This keeps comparison surgical and intentional.
+
+Custom Comparator
+
+You may supply your own comparison logic:
+
+useRenderShield(props, {
+  customCompare: (prev, next) => prev.id === next.id
+});
+
+
+If provided:
+
+The custom comparator takes precedence.
+
+Comparison logic remains explicit and user-defined.
+
+No additional heuristics are applied.
+
+Debug Diagnostics
+
+Enable diagnostic logging:
+
+useRenderShield(props, {
+  watch: ["user.id"],
+  debug: true
+});
+
+
+Console output includes:
+
+Whether shielding occurred
+
+Render count
+
+Changed keys
+
+Stable keys
+
+Watched path results
+
+Classification severity
+
+Logs are disabled in production builds.
+
+Debug mode is strictly for development analysis.
+
+Optional Visual HUD (v0.3+)
+
+You may enable a minimal visual overlay during development:
+
+useRenderShield(props, {
+  watch: ["user.id"],
+  debug: true,
+  visual: true
+});
+
+
+When:
+
+debug === true
+
+visual === true
+
+a render was successfully shielded
+
+A small, temporary development HUD toast appears.
+
+Design constraints:
+
+SSR safe (document guard)
+
+No React lifecycle injection
+
+Single shared DOM node
+
+Auto-removal after ~2 seconds
+
+No global state mutation
+
+This is a development instrument — not a UI system.
+
+Higher-Order Component
+const Shielded = withRenderShield(Component, {
+  watch: ["user.id"],
+  debug: true
+});
+
+
+The HOC:
+
+Wraps React.memo
+
+Applies the same comparison logic
+
+Does not mutate props
+
+Does not inject state
+
+Does not modify component behavior
+
+It influences rerender decisions only.
+
+Severity Classification
+
+When debug mode is enabled, comparisons are classified as:
+
+Stable
+
+Changed (non-UI key)
+
+Changed (watched key)
+
+Custom compare triggered
+
+These classifications are informational.
+
+They do not alter runtime behavior.
+
+Example: The Invisible Cascade
+
+A parent updates user.lastActive every 800ms.
+
+Your component only depends on user.id.
+
+Without structured comparison, rerenders may cascade silently.
+
+With RenderShield:
+
+useRenderShield(props, {
+  watch: ["user.id"],
+  debug: true
+});
+
+
+Only user.id is deep-compared.
+
+Unrelated changes are classified and reported.
+
+You don’t guess.
+
+You verify.
+
+What It Is Not
+
+RenderShield React is not:
+
+A compiler
+
+A code transformation tool
+
+A React internals patch
+
+A guaranteed performance fix
+
+A global runtime modifier
+
+A full deep-equality engine by default
+
+It favors clarity over automation.
+
+It prefers explicit control over hidden behavior.
+
+Design Constraints
+
+RenderShield React:
+
+Is React 18+ compatible
+
+Does not rely on experimental APIs
+
+Does not mutate inputs
+
+Does not modify React internals
+
+Does not introduce global side effects
+
+Avoids deep recursion unless explicitly requested
+
+Keeps shallow comparison O(n)
+
+It prefers doing nothing over doing the wrong thing.
+
+Intended Use Cases
+
+RenderShield React works best when:
+
+Diagnosing rerender cascades
+
+Auditing AI-generated components
+
+Verifying React.memo effectiveness
+
+Validating watch-path stability
+
+Building controlled component boundaries
+
+Teaching render mechanics to teams
+
+It is a diagnostic surface.
+
+Not an optimization promise.
+
+Status
+
+v0.2.x
+
+Core hook stable
+
+HOC stable
+
+Watch-path targeting validated
+
+Type-safe
+
+Tests passing
+
+CJS, ESM, and DTS builds
+
+v0.3.x introduces optional visual development HUD support.
+
+Future versions may explore extended diagnostics or tooling layers.
+The core remains intentionally conservative.
+
+License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,74 @@
+import React from 'react';
+
+type RenderShieldSeverity = "Stable" | "Changed (non-UI key)" | "Changed (watched key)" | "Custom compare triggered";
+/** @deprecated Use RenderShieldSeverity. Kept for backward compatibility. */
+type DiffSeverity = RenderShieldSeverity;
+type RenderShieldDiff = {
+    componentName?: string;
+    shielded: boolean;
+    renderCount: number;
+    changedKeys: string[];
+    stableKeys: string[];
+    watchedChanged: string[];
+    watchedStable: string[];
+    severity: RenderShieldSeverity;
+    /**
+     * v0.3.0
+     * Enables the dev HUD toast for this report event.
+     * Set by hook/HOC from RenderShieldOptions.visual.
+     */
+    visual?: boolean;
+};
+type RenderShieldOptions<T> = {
+    watch?: string[];
+    debug?: boolean;
+    /**
+     * v0.3.0
+     * When true, render shielded events will show a small dev HUD toast.
+     */
+    visual?: boolean;
+    customCompare?: (prev: T, next: T) => boolean;
+    /**
+     * Optional explicit name for hook-based usage (HOC derives name automatically).
+     */
+    componentName?: string;
+};
+
+/**
+ * useRenderShield
+ * - Shields by returning the previous value when the selected comparison says "equal".
+ * - Emits dev-only diagnostics when options.debug === true
+ *
+ * v0.3.0:
+ * - options.visual enables the dev HUD toast (only when shielded).
+ * - visual flag is carried into the report diff, so report.ts can decide.
+ */
+declare function useRenderShield<T>(value: T, options?: RenderShieldOptions<T>): T;
+
+declare function withRenderShield<P extends object>(Component: React.ComponentType<P>, options?: RenderShieldOptions<P>): React.MemoExoticComponent<React.ComponentType<P>>;
+
+declare function getShallowDiff(prev: any, next: any): {
+    equal: boolean;
+    changedKeys: string[];
+    stableKeys: string[];
+};
+
+declare function getAtPath(obj: any, path: string): any;
+/**
+ * Deep compare ONLY the values at watched paths.
+ * This is intentionally targeted: no full-object deep recursion.
+ */
+declare function compareWatchedPaths<T>(prev: T, next: T, watch: string[]): {
+    watchedChanged: string[];
+    watchedStable: string[];
+    watchedEqual: boolean;
+};
+/**
+ * Minimal deep equality for watched values.
+ * - Cycle-safe
+ * - Handles primitives, arrays, plain objects
+ * - Not intended for huge graphs (watch paths should stay small + intentional)
+ */
+declare function deepEqual(a: any, b: any, seen?: WeakMap<object, object>): boolean;
+
+export { type DiffSeverity, type RenderShieldDiff, type RenderShieldOptions, compareWatchedPaths, deepEqual, getAtPath, getShallowDiff, useRenderShield, withRenderShield };

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import React from 'react';
+
+type RenderShieldSeverity = "Stable" | "Changed (non-UI key)" | "Changed (watched key)" | "Custom compare triggered";
+/** @deprecated Use RenderShieldSeverity. Kept for backward compatibility. */
+type DiffSeverity = RenderShieldSeverity;
+type RenderShieldDiff = {
+    componentName?: string;
+    shielded: boolean;
+    renderCount: number;
+    changedKeys: string[];
+    stableKeys: string[];
+    watchedChanged: string[];
+    watchedStable: string[];
+    severity: RenderShieldSeverity;
+    /**
+     * v0.3.0
+     * Enables the dev HUD toast for this report event.
+     * Set by hook/HOC from RenderShieldOptions.visual.
+     */
+    visual?: boolean;
+};
+type RenderShieldOptions<T> = {
+    watch?: string[];
+    debug?: boolean;
+    /**
+     * v0.3.0
+     * When true, render shielded events will show a small dev HUD toast.
+     */
+    visual?: boolean;
+    customCompare?: (prev: T, next: T) => boolean;
+    /**
+     * Optional explicit name for hook-based usage (HOC derives name automatically).
+     */
+    componentName?: string;
+};
+
+/**
+ * useRenderShield
+ * - Shields by returning the previous value when the selected comparison says "equal".
+ * - Emits dev-only diagnostics when options.debug === true
+ *
+ * v0.3.0:
+ * - options.visual enables the dev HUD toast (only when shielded).
+ * - visual flag is carried into the report diff, so report.ts can decide.
+ */
+declare function useRenderShield<T>(value: T, options?: RenderShieldOptions<T>): T;
+
+declare function withRenderShield<P extends object>(Component: React.ComponentType<P>, options?: RenderShieldOptions<P>): React.MemoExoticComponent<React.ComponentType<P>>;
+
+declare function getShallowDiff(prev: any, next: any): {
+    equal: boolean;
+    changedKeys: string[];
+    stableKeys: string[];
+};
+
+declare function getAtPath(obj: any, path: string): any;
+/**
+ * Deep compare ONLY the values at watched paths.
+ * This is intentionally targeted: no full-object deep recursion.
+ */
+declare function compareWatchedPaths<T>(prev: T, next: T, watch: string[]): {
+    watchedChanged: string[];
+    watchedStable: string[];
+    watchedEqual: boolean;
+};
+/**
+ * Minimal deep equality for watched values.
+ * - Cycle-safe
+ * - Handles primitives, arrays, plain objects
+ * - Not intended for huge graphs (watch paths should stay small + intentional)
+ */
+declare function deepEqual(a: any, b: any, seen?: WeakMap<object, object>): boolean;
+
+export { type DiffSeverity, type RenderShieldDiff, type RenderShieldOptions, compareWatchedPaths, deepEqual, getAtPath, getShallowDiff, useRenderShield, withRenderShield };

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";var A=Object.create;var m=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var q=Object.getOwnPropertyNames;var I=Object.getPrototypeOf,E=Object.prototype.hasOwnProperty;var P=(e,n)=>{for(var t in n)m(e,t,{get:n[t],enumerable:!0})},x=(e,n,t,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let r of q(n))!E.call(e,r)&&r!==t&&m(e,r,{get:()=>n[r],enumerable:!(o=T(n,r))||o.enumerable});return e};var W=(e,n,t)=>(t=e!=null?A(I(e)):{},x(n||!e||!e.__esModule?m(t,"default",{value:e,enumerable:!0}):t,e)),$=e=>x(m({},"__esModule",{value:!0}),e);var Y={};P(Y,{compareWatchedPaths:()=>p,deepEqual:()=>y,getAtPath:()=>b,getShallowDiff:()=>f,useRenderShield:()=>j,withRenderShield:()=>D});module.exports=$(Y);var g=require("react");function f(e,n){if(Object.is(e,n))return{equal:!0,changedKeys:[],stableKeys:M(n)};if(!S(e)||!S(n))return{equal:!1,changedKeys:["(value)"],stableKeys:[]};let t=Object.keys(e),o=Object.keys(n),r=new Set([...t,...o]),a=[],l=[];for(let i of r){let s=e[i],d=n[i];Object.is(s,d)?l.push(i):a.push(i)}return{equal:a.length===0,changedKeys:a,stableKeys:l}}function S(e){return e!==null&&typeof e=="object"}function M(e){return S(e)?Object.keys(e):[]}function b(e,n){if(e==null)return;let t=U(n),o=e;for(let r of t){if(o==null)return;o=o[r]}return o}function p(e,n,t){let o=[],r=[];for(let a of t){let l=b(e,a),i=b(n,a);y(l,i)?r.push(a):o.push(a)}return{watchedChanged:o,watchedStable:r,watchedEqual:o.length===0}}function y(e,n,t=new WeakMap){if(Object.is(e,n))return!0;let o=K(e),r=K(n);if(!o||!r)return!1;let a=t.get(e);if(a&&a===n)return!0;if(t.set(e,n),Array.isArray(e)||Array.isArray(n)){if(!Array.isArray(e)||!Array.isArray(n)||e.length!==n.length)return!1;for(let s=0;s<e.length;s++)if(!y(e[s],n[s],t))return!1;return!0}let l=Object.keys(e),i=Object.keys(n);if(l.length!==i.length)return!1;for(let s of l)if(!Object.prototype.hasOwnProperty.call(n,s))return!1;for(let s of l)if(!y(e[s],n[s],t))return!1;return!0}function K(e){return e!==null&&typeof e=="object"}function U(e){let n=[],t=e.replace(/\[(\d+)\]/g,".$1");for(let o of t.split(".").filter(Boolean)){let r=Number(o);n.push(Number.isInteger(r)&&String(r)===o?r:o)}return n}var C=new Map,R=!1;function u(e){if(B())return;let n=F(e);C.set(n,{key:n,diff:e}),R||(R=!0,Promise.resolve().then(z))}function z(){for(let{diff:e}of C.values())V(e);C.clear(),R=!1}function V(e){let n=e.componentName?`<${e.componentName}>`:"<Component>",t=`[RenderShield] ${n}`;console.groupCollapsed(t),console.log("Shielded:",e.shielded),console.log("Render count:",e.renderCount),console.log("Changed:",e.changedKeys),console.log("Stable:",e.stableKeys),(e.watchedChanged.length||e.watchedStable.length)&&(console.log("Watched changed:",e.watchedChanged),console.log("Watched stable:",e.watchedStable)),console.log("Severity:",e.severity),console.groupEnd(),e.shielded&&e.visual===!0&&H(n,e.severity)}function B(){try{return typeof process<"u"&&!!process.env&&process.env.NODE_ENV==="production"}catch{return!1}}function H(e,n){if(typeof document>"u"||typeof window>"u")return;let t="render-shield-toast",o="render-shield-toast",r=document.getElementById(t);r&&r.remove();let a=document.createElement("div");a.id=t,a.className=o,Object.assign(a.style,{position:"fixed",bottom:"20px",right:"20px",background:"rgba(12, 16, 22, 0.92)",color:"white",padding:"12px 14px",borderRadius:"12px",boxShadow:"0 14px 38px rgba(0,0,0,0.38)",fontFamily:'ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, "Apple Color Emoji", "Segoe UI Emoji"',fontSize:"13px",lineHeight:"1.25",fontWeight:"650",zIndex:"2147483647",display:"flex",alignItems:"center",gap:"10px",border:"1px solid rgba(255,255,255,0.12)",backdropFilter:"blur(8px)",transform:"translateY(12px)",opacity:"0",transition:"transform 180ms ease, opacity 180ms ease",pointerEvents:"none",maxWidth:"340px"});let l=N(e),i=N(n);a.innerHTML=`
+    <div style="display:flex; align-items:center; gap:10px;">
+      <span aria-hidden="true" style="font-size:16px; line-height:1;">\u{1F6E1}\uFE0F</span>
+      <div style="display:flex; flex-direction:column; gap:2px;">
+        <div style="opacity:0.98">
+          <span style="color: #35d07f; font-weight: 800;">${l}</span> shielded
+        </div>
+        <div style="font-size:11px; font-weight:600; opacity:0.78">
+          ${i}
+        </div>
+      </div>
+    </div>
+  `,document.body.appendChild(a),requestAnimationFrame(()=>{a.style.transform="translateY(0)",a.style.opacity="1"}),window.setTimeout(()=>{a.style.transform="translateY(8px)",a.style.opacity="0",window.setTimeout(()=>a.remove(),220)},2e3)}function N(e){return e.replaceAll("&","&amp;").replaceAll("<","&lt;").replaceAll(">","&gt;").replaceAll('"',"&quot;").replaceAll("'","&#039;")}function F(e){let n=e.componentName??"Anonymous",t=[e.shielded?"S1":"S0",e.severity,e.changedKeys.join(","),"|W|",e.watchedChanged.join(",")].join(":");return`${n}::${t}`}function j(e,n){let t=n??{},o=(0,g.useRef)(null),r=(0,g.useRef)(0);r.current+=1;let a=o.current,l=(0,g.useMemo)(()=>{if(a===null){let c=e&&typeof e=="object"?Object.keys(e):[],h={componentName:t.componentName,shielded:!1,renderCount:r.current,changedKeys:[],stableKeys:c,watchedChanged:[],watchedStable:t.watch??[],severity:"Stable",visual:!!t.visual};return{shielded:!1,nextValue:e,shouldReportInitial:!!t.debug,initialDiff:h,diff:void 0}}if(typeof t.customCompare=="function"){let c=t.customCompare(a,e),h={componentName:t.componentName,shielded:c,renderCount:r.current,changedKeys:[],stableKeys:[],watchedChanged:[],watchedStable:t.watch??[],severity:"Custom compare triggered",visual:!!t.visual};return{shielded:c,nextValue:c?a:e,shouldReportInitial:!1,initialDiff:void 0,diff:h}}let i=L(a,e),s=i.changedKeys,d=i.stableKeys;if(t.watch&&t.watch.length>0){let c=p(a,e,t.watch),h=c.watchedEqual,k={componentName:t.componentName,shielded:h,renderCount:r.current,changedKeys:s,stableKeys:d,watchedChanged:c.watchedChanged,watchedStable:c.watchedStable,severity:c.watchedChanged.length>0?"Changed (watched key)":s.length>0?"Changed (non-UI key)":"Stable",visual:!!t.visual};return{shielded:h,nextValue:h?a:e,shouldReportInitial:!1,initialDiff:void 0,diff:k}}let w=i.equal,O={componentName:t.componentName,shielded:w,renderCount:r.current,changedKeys:s,stableKeys:d,watchedChanged:[],watchedStable:[],severity:s.length>0?"Changed (non-UI key)":"Stable",visual:!!t.visual};return{shielded:w,nextValue:w?a:e,shouldReportInitial:!1,initialDiff:void 0,diff:O}},[e,t.componentName,t.debug,t.visual,t.customCompare,t.watch?.join("|")]);return a===null?(o.current=e,l.shouldReportInitial&&l.initialDiff&&u(l.initialDiff),e):(t.debug&&l.diff&&u(l.diff),l.shielded?o.current:(o.current=e,e))}function L(e,n){try{return f(e,n)}catch{return{equal:!1,changedKeys:["(unavailable)"],stableKeys:[]}}}var v=W(require("react"));function D(e,n){let t=n??{},o=e.displayName||e.name||"Component",r=v.default.memo(e,(a,l)=>{if(typeof t.customCompare=="function"){let s=t.customCompare(a,l);return t.debug&&u({componentName:o,shielded:s,renderCount:NaN,changedKeys:[],stableKeys:[],watchedChanged:[],watchedStable:[],severity:"Custom compare triggered"}),s}let i=f(a,l);if(t.watch&&t.watch.length>0){let s=p(a,l,t.watch),d=s.watchedEqual;return t.debug&&u({componentName:o,shielded:d,renderCount:NaN,changedKeys:i.changedKeys,stableKeys:i.stableKeys,watchedChanged:s.watchedChanged,watchedStable:s.watchedStable,severity:s.watchedChanged.length>0?"Changed (watched key)":i.changedKeys.length>0?"Changed (non-UI key)":"Stable"}),d}return t.debug&&u({componentName:o,shielded:i.equal,renderCount:NaN,changedKeys:i.changedKeys,stableKeys:i.stableKeys,watchedChanged:[],watchedStable:[],severity:i.changedKeys.length>0?"Changed (non-UI key)":"Stable"}),i.equal});return r.displayName=`withRenderShield(${o})`,r}0&&(module.exports={compareWatchedPaths,deepEqual,getAtPath,getShallowDiff,useRenderShield,withRenderShield});

package/dist/index.mjs

@@ -0,0 +1,13 @@
+import{useMemo as q,useRef as x}from"react";function f(e,n){if(Object.is(e,n))return{equal:!0,changedKeys:[],stableKeys:j(n)};if(!m(e)||!m(n))return{equal:!1,changedKeys:["(value)"],stableKeys:[]};let t=Object.keys(e),o=Object.keys(n),r=new Set([...t,...o]),a=[],l=[];for(let i of r){let s=e[i],d=n[i];Object.is(s,d)?l.push(i):a.push(i)}return{equal:a.length===0,changedKeys:a,stableKeys:l}}function m(e){return e!==null&&typeof e=="object"}function j(e){return m(e)?Object.keys(e):[]}function b(e,n){if(e==null)return;let t=v(n),o=e;for(let r of t){if(o==null)return;o=o[r]}return o}function p(e,n,t){let o=[],r=[];for(let a of t){let l=b(e,a),i=b(n,a);y(l,i)?r.push(a):o.push(a)}return{watchedChanged:o,watchedStable:r,watchedEqual:o.length===0}}function y(e,n,t=new WeakMap){if(Object.is(e,n))return!0;let o=C(e),r=C(n);if(!o||!r)return!1;let a=t.get(e);if(a&&a===n)return!0;if(t.set(e,n),Array.isArray(e)||Array.isArray(n)){if(!Array.isArray(e)||!Array.isArray(n)||e.length!==n.length)return!1;for(let s=0;s<e.length;s++)if(!y(e[s],n[s],t))return!1;return!0}let l=Object.keys(e),i=Object.keys(n);if(l.length!==i.length)return!1;for(let s of l)if(!Object.prototype.hasOwnProperty.call(n,s))return!1;for(let s of l)if(!y(e[s],n[s],t))return!1;return!0}function C(e){return e!==null&&typeof e=="object"}function v(e){let n=[],t=e.replace(/\[(\d+)\]/g,".$1");for(let o of t.split(".").filter(Boolean)){let r=Number(o);n.push(Number.isInteger(r)&&String(r)===o?r:o)}return n}var w=new Map,S=!1;function u(e){if(k())return;let n=T(e);w.set(n,{key:n,diff:e}),S||(S=!0,Promise.resolve().then(D))}function D(){for(let{diff:e}of w.values())O(e);w.clear(),S=!1}function O(e){let n=e.componentName?`<${e.componentName}>`:"<Component>",t=`[RenderShield] ${n}`;console.groupCollapsed(t),console.log("Shielded:",e.shielded),console.log("Render count:",e.renderCount),console.log("Changed:",e.changedKeys),console.log("Stable:",e.stableKeys),(e.watchedChanged.length||e.watchedStable.length)&&(console.log("Watched changed:",e.watchedChanged),console.log("Watched stable:",e.watchedStable)),console.log("Severity:",e.severity),console.groupEnd(),e.shielded&&e.visual===!0&&A(n,e.severity)}function k(){try{return typeof process<"u"&&!!process.env&&process.env.NODE_ENV==="production"}catch{return!1}}function A(e,n){if(typeof document>"u"||typeof window>"u")return;let t="render-shield-toast",o="render-shield-toast",r=document.getElementById(t);r&&r.remove();let a=document.createElement("div");a.id=t,a.className=o,Object.assign(a.style,{position:"fixed",bottom:"20px",right:"20px",background:"rgba(12, 16, 22, 0.92)",color:"white",padding:"12px 14px",borderRadius:"12px",boxShadow:"0 14px 38px rgba(0,0,0,0.38)",fontFamily:'ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, "Apple Color Emoji", "Segoe UI Emoji"',fontSize:"13px",lineHeight:"1.25",fontWeight:"650",zIndex:"2147483647",display:"flex",alignItems:"center",gap:"10px",border:"1px solid rgba(255,255,255,0.12)",backdropFilter:"blur(8px)",transform:"translateY(12px)",opacity:"0",transition:"transform 180ms ease, opacity 180ms ease",pointerEvents:"none",maxWidth:"340px"});let l=R(e),i=R(n);a.innerHTML=`
+    <div style="display:flex; align-items:center; gap:10px;">
+      <span aria-hidden="true" style="font-size:16px; line-height:1;">\u{1F6E1}\uFE0F</span>
+      <div style="display:flex; flex-direction:column; gap:2px;">
+        <div style="opacity:0.98">
+          <span style="color: #35d07f; font-weight: 800;">${l}</span> shielded
+        </div>
+        <div style="font-size:11px; font-weight:600; opacity:0.78">
+          ${i}
+        </div>
+      </div>
+    </div>
+  `,document.body.appendChild(a),requestAnimationFrame(()=>{a.style.transform="translateY(0)",a.style.opacity="1"}),window.setTimeout(()=>{a.style.transform="translateY(8px)",a.style.opacity="0",window.setTimeout(()=>a.remove(),220)},2e3)}function R(e){return e.replaceAll("&","&amp;").replaceAll("<","&lt;").replaceAll(">","&gt;").replaceAll('"',"&quot;").replaceAll("'","&#039;")}function T(e){let n=e.componentName??"Anonymous",t=[e.shielded?"S1":"S0",e.severity,e.changedKeys.join(","),"|W|",e.watchedChanged.join(",")].join(":");return`${n}::${t}`}function I(e,n){let t=n??{},o=x(null),r=x(0);r.current+=1;let a=o.current,l=q(()=>{if(a===null){let c=e&&typeof e=="object"?Object.keys(e):[],h={componentName:t.componentName,shielded:!1,renderCount:r.current,changedKeys:[],stableKeys:c,watchedChanged:[],watchedStable:t.watch??[],severity:"Stable",visual:!!t.visual};return{shielded:!1,nextValue:e,shouldReportInitial:!!t.debug,initialDiff:h,diff:void 0}}if(typeof t.customCompare=="function"){let c=t.customCompare(a,e),h={componentName:t.componentName,shielded:c,renderCount:r.current,changedKeys:[],stableKeys:[],watchedChanged:[],watchedStable:t.watch??[],severity:"Custom compare triggered",visual:!!t.visual};return{shielded:c,nextValue:c?a:e,shouldReportInitial:!1,initialDiff:void 0,diff:h}}let i=E(a,e),s=i.changedKeys,d=i.stableKeys;if(t.watch&&t.watch.length>0){let c=p(a,e,t.watch),h=c.watchedEqual,N={componentName:t.componentName,shielded:h,renderCount:r.current,changedKeys:s,stableKeys:d,watchedChanged:c.watchedChanged,watchedStable:c.watchedStable,severity:c.watchedChanged.length>0?"Changed (watched key)":s.length>0?"Changed (non-UI key)":"Stable",visual:!!t.visual};return{shielded:h,nextValue:h?a:e,shouldReportInitial:!1,initialDiff:void 0,diff:N}}let g=i.equal,K={componentName:t.componentName,shielded:g,renderCount:r.current,changedKeys:s,stableKeys:d,watchedChanged:[],watchedStable:[],severity:s.length>0?"Changed (non-UI key)":"Stable",visual:!!t.visual};return{shielded:g,nextValue:g?a:e,shouldReportInitial:!1,initialDiff:void 0,diff:K}},[e,t.componentName,t.debug,t.visual,t.customCompare,t.watch?.join("|")]);return a===null?(o.current=e,l.shouldReportInitial&&l.initialDiff&&u(l.initialDiff),e):(t.debug&&l.diff&&u(l.diff),l.shielded?o.current:(o.current=e,e))}function E(e,n){try{return f(e,n)}catch{return{equal:!1,changedKeys:["(unavailable)"],stableKeys:[]}}}import P from"react";function W(e,n){let t=n??{},o=e.displayName||e.name||"Component",r=P.memo(e,(a,l)=>{if(typeof t.customCompare=="function"){let s=t.customCompare(a,l);return t.debug&&u({componentName:o,shielded:s,renderCount:NaN,changedKeys:[],stableKeys:[],watchedChanged:[],watchedStable:[],severity:"Custom compare triggered"}),s}let i=f(a,l);if(t.watch&&t.watch.length>0){let s=p(a,l,t.watch),d=s.watchedEqual;return t.debug&&u({componentName:o,shielded:d,renderCount:NaN,changedKeys:i.changedKeys,stableKeys:i.stableKeys,watchedChanged:s.watchedChanged,watchedStable:s.watchedStable,severity:s.watchedChanged.length>0?"Changed (watched key)":i.changedKeys.length>0?"Changed (non-UI key)":"Stable"}),d}return t.debug&&u({componentName:o,shielded:i.equal,renderCount:NaN,changedKeys:i.changedKeys,stableKeys:i.stableKeys,watchedChanged:[],watchedStable:[],severity:i.changedKeys.length>0?"Changed (non-UI key)":"Stable"}),i.equal});return r.displayName=`withRenderShield(${o})`,r}export{p as compareWatchedPaths,y as deepEqual,b as getAtPath,f as getShallowDiff,I as useRenderShield,W as withRenderShield};

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "@lownoise-studio/render-shield-react",
+    "version": "0.3.0-alpha.1",
+    "description": "Lightweight React render diff shielding with structured diagnostics.",
+    "license": "MIT",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "npx tsup",
+        "dev": "npx tsup --watch",
+        "test": "vitest"
+    },
+    "peerDependencies": {
+        "react": ">=18"
+    },
+    "devDependencies": {
+        "tsup": "^8.0.0",
+        "vitest": "^1.6.0",
+        "@testing-library/react": "^14.0.0",
+        "jsdom": "^24.0.0",
+        "react": "^18.0.0",
+        "react-dom": "^18.0.0",
+        "typescript": "^5.0.0"
+    }
+}