fix: 🐛 clear state before setState to prevent stale keys from persisting

- Clear widget.state before calling setState when both setProps and setState are available
- This prevents load()-generated state keys from merging with Storybook-provided state
- Ensures Storybook args.widget.state remains authoritative during widget reuse
- Add test coverage for state clearing behavior
- Fix documentation example by adding missing WidgetDescription function definition

Author: Jiří Fencl

packages/tool-storybook/src/__tests__/indexSpec.js

@@ -168,6 +168,32 @@ describe('Merkur tool storybook', () => {
       expect(first.state).toEqual({ count: 99 });
     });
 
+    it('should clear state before calling setState to avoid merging with load()-generated keys (hasSetProps && hasSetState)', async () => {
+      let loader = createWidgetLoader({ widgetProperties, render });
+
+      let { widget: first } = await loader(storyArgs);
+
+      // Simulate setProps/load() adding keys to state
+      jest.spyOn(first, 'setProps').mockImplementation(async () => {
+        first.state = { loadGenerated: 'stale', anotherKey: 'old' };
+      });
+
+      // Track what state was present when setState was called
+      let stateBeforeSetState;
+      jest.spyOn(first, 'setState').mockImplementation(async (newState) => {
+        stateBeforeSetState = { ...first.state };
+        first.state = { ...first.state, ...newState };
+      });
+
+      storyArgs.args.widget.state = { count: 42 };
+      await loader(storyArgs);
+
+      // State should have been cleared ({}) before setState was called
+      expect(stateBeforeSetState).toEqual({});
+      // Final state should only contain what setState received, not load()-generated keys
+      expect(first.state).toEqual({ count: 42 });
+    });
+
     it('should preserve story state when only setProps is available and load() overwrites state (hasSetProps && !hasSetState)', async () => {
       let loader = createWidgetLoader({ widgetProperties, render });
 

packages/tool-storybook/src/index.js

@@ -59,6 +59,9 @@ function createWidgetLoader({ render, widgetProperties }) {
       if (hasSetProps && hasSetState) {
         widget.props = {};
         await widget.setProps(nextProps);
+        // Clear state so that Storybook-provided state replaces any previous or
+        // load()-generated keys instead of merging with them.
+        widget.state = {};
         await widget.setState(nextState);
         return { widget };
       }

website/docs/storybook-integration-into-merkur.md

@@ -328,6 +328,15 @@ The `createVanillaRenderer` in `preview.mjs` handles all the DOM creation and re
 For stories that need custom logic (e.g., overriding specific widget properties), you can provide a custom render function:
 
 ```javascript
+// Simple example render function for a vanilla widget.
+// In your project, replace this with your actual widget render implementation.
+const WidgetDescription = (widget) => `
+  <div>
+    <h2>${widget.name}</h2>
+    <p>Version: ${widget.version}</p>
+  </div>
+`;
+
 export const CustomWidget = {
   render: (args, { loaded: { widget } }) => {
     const container = document.createElement('div');