diff --git a/.gitignore b/.gitignore
index 47e893a7c..31f01c16e 100755
--- a/.gitignore
+++ b/.gitignore
@@ -12,6 +12,7 @@ tests/test-case/dist
 
 # for my ai friends
 ai/meta/agent-guestbook.md
+ai/meta/jisei.md
 
 # Numerous always-ignore extensions
 *.diff
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
index 438f2efcb..8df43a4dd 100644
--- a/RELEASE-NOTES.md
+++ b/RELEASE-NOTES.md
@@ -4,6 +4,15 @@ This is a pre-release version and APIs will change quickly. Before `1.0` release
 
 Please note after `1.0` Semver will be followed using normal protocols.
 
+# Version 0.13.0
+
+* **Query** - Added `clippingParent` to find closest ancestor which will clip the current element
+* **Query** - `offsetParent` has been renamed to `containingParent` and now includes many other possible containing parent checks like `will-change` and `filter`.
+* **Query** - `setting()` can now be used as a getter.
+* **Query** - Added `.data()` for getting and setting html data
+* **Query** - Added `.slice()` for returning a portion of the element collection
+* **Query** - Fixed `offsetParent` to correctly return offset parent for willChange
+
 # Version 0.12.4-1
 * **Tailwind** - `@semantic-ui/tailwind` and `tailwindcss-iso` now have bundled CDN version to avoid issues importing css files in browser via esm. Modified `tailwind` package to accomodate this change.
 * **Tailwind** - Removed bundled `wasm` files, these are now part of the generic `tailwindcss-iso` package.
diff --git a/ai/guides/html-css-style-guide.md b/ai/guides/html-css-style-guide.md
index b1ea3b71b..c79cee9f3 100644
--- a/ai/guides/html-css-style-guide.md
+++ b/ai/guides/html-css-style-guide.md
@@ -1,6 +1,6 @@
 # Semantic UI HTML & CSS Style Guide
 
-Based on analysis of canonical examples authored by Jack Lukic, this guide captures the distinctive patterns and philosophies for writing HTML and CSS within Semantic UI web components.
+This guide captures the distinctive patterns and philosophies for writing HTML and CSS within Semantic UI web components.
 
 ## Core Philosophy: Natural Language Applied to Markup
 
@@ -467,4 +467,4 @@ Your HTML and CSS style reflects a sophisticated understanding of how natural la
 - **Smooth interactions** with design system transitions
 - **Seamless accessibility** integration
 
-This approach creates code that leverages the full power of the design system while maintaining component-specific customization where needed.
\ No newline at end of file
+This approach creates code that leverages the full power of the design system while maintaining component-specific customization where needed.
diff --git a/ai/specialized/query-system-guide.md b/ai/packages/query.md
similarity index 75%
rename from ai/specialized/query-system-guide.md
rename to ai/packages/query.md
index 612dc11c1..c11e59776 100644
--- a/ai/specialized/query-system-guide.md
+++ b/ai/packages/query.md
@@ -1,53 +1,78 @@
 # Semantic UI Query System Guide
 
-**For AI agents working with Semantic UI's `@semantic-ui/query` package**
+> **For:** AI agents working with DOM querying and manipulation in Semantic UI  
+> **Purpose:** Comprehensive reference for the Query package and component debugging  
+> **Prerequisites:** Basic understanding of DOM and Shadow DOM concepts  
+> **Related:** [Mental Model](../foundations/mental-model.md) • [Component Guide](../guides/component-generation-instructions.md) • [Quick Reference](../foundations/quick-reference.md)  
+> **Back to:** [Documentation Hub](../00-START-HERE.md)
 
-## Overview
+---
 
-The `@semantic-ui/query` package is a standalone DOM querying and manipulation library that provides jQuery-like functionality with modern JavaScript features. It's designed specifically to handle Shadow DOM traversal and component-aware querying while remaining lightweight and focused.
+## Table of Contents
 
-## Package Structure
+- [Core Query Concepts](#core-query-concepts)
+- [Shadow DOM Traversal Strategy](#shadow-dom-traversal-strategy)
+- [Component Instance Access](#component-instance-access)
+- [Component Debugging Workflow](#component-debugging-workflow)
+- [Event System Integration](#event-system-integration)
+- [Performance Considerations](#performance-considerations)
+- [Advanced Query Patterns](#advanced-query-patterns)
+- [Troubleshooting Common Issues](#troubleshooting-common-issues)
 
-```
-@semantic-ui/query
-├── Query         ← Main query class with DOM manipulation methods
-├── $ function    ← Standard DOM querying (respects Shadow DOM boundaries)  
-├── $$ function   ← Deep querying (crosses Shadow DOM boundaries)
-└── Utilities     ← Global management and aliasing functions
-```
+---
+
+## Core Query Concepts
+
+### The Dual Query System
+
+Semantic UI provides two entry points for DOM querying, each with distinct capabilities:
 
-**Main Exports**:
 ```javascript
-import { $, $$, Query, exportGlobals, restoreGlobals, useAlias } from '@semantic-ui/query';
+import { $, $$ } from '@semantic-ui/query';
+
+// Standard DOM querying (respects Shadow DOM boundaries)
+$('button')              // Finds buttons in light DOM only
+$('ui-dropdown')         // Finds dropdown components, but not their internal structure
+
+// Deep querying (pierces Shadow DOM boundaries)  
+$$('button')             // Finds buttons in light AND shadow DOM
+$$('ui-dropdown .item')  // Finds .item elements inside dropdown's shadow DOM
 ```
 
-## Core Functions
+**Mental Model**: Think of `$` as "CSS selectors" and `$$` as "CSS selectors that understand web components."
+
+### Query Instance Architecture
 
-### $ - Standard DOM Querying
+Every Query instance contains:
 
-The `$` function provides standard DOM querying that respects Shadow DOM boundaries.
+```javascript
+const $elements = $('div');
+
+// Core properties
+$elements.length         // Number of matched elements
+$elements.selector       // Original selector used
+$elements.options        // Query configuration (root, pierceShadow)
+$elements[0], $elements[1] // Array-like access to elements
+
+// Chaining system
+$elements.find('.child')  // Returns new Query instance
+$elements.chain([newEl])  // Create Query with specific elements
+```
+
+### Query Options and Configuration
 
 ```javascript
-import { $ } from '@semantic-ui/query';
-
-// Query selectors (standard CSS selectors)
-$('.button')                    // All elements with class 'button' in light DOM
-$('#main')                      // Element with id 'main'
-$('input[type="text"]')         // All text inputs
-$('div > .child')               // Direct child selectors
-
-// Create elements from HTML
-$('<div class="new-element">Content</div>')
-$('<span>Text</span>')
-
-// Wrap existing elements
-$(document.body)                // Wrap body element
-$(elementArray)                 // Wrap array of elements
-$(nodeList)                     // Wrap NodeList
-
-// Global selectors
-$('window')                     // Window object (special handling)
-$('body')                       // Document body
+// Root scoping
+$('button', { root: shadowRoot })           // Query within specific root
+$('input', { root: document.getElementById('form') })
+
+// Shadow DOM piercing
+$('button', { pierceShadow: true })         // Equivalent to $$('button')
+
+// Component-scoped querying
+const dropdown = $('ui-dropdown').get(0);
+$('button', { root: dropdown.shadowRoot }); // Query inside component
+```
 ```
 
 ### $$ - Deep DOM Querying
@@ -93,50 +118,52 @@ The Query class provides a comprehensive set of methods organized into logical c
 - `get(index)` - Get element at index
 - `eq(index)` - Get new Query object with element at index
 - `first()`, `last()` - Get first/last element as new Query
-- `slice(start, end)` - Get subset of elements
 
 ### DOM Traversal
 - `find(selector)` - Find descendants
-- `parent()`, `parents()` - Get parent elements
-- `children()`, `siblings()` - Get child/sibling elements
-- `next()`, `prev()` - Get adjacent siblings
+- `parent(selector)` - Get parent elements
+- `children(selector)`, `siblings(selector)` - Get child/sibling elements
+- `next(selector)`, `prev(selector)` - Get adjacent siblings
 - `closest(selector)` - Find closest ancestor matching selector
 
 ### Content Manipulation
 - `html()`, `html(content)` - Get/set innerHTML
 - `text()`, `text(content)` - Get/set textContent
 - `val()`, `val(value)` - Get/set form element values
-- `append()`, `prepend()` - Add content to elements
-- `before()`, `after()` - Add content around elements
+- `append(content)`, `prepend(content)` - Add content to elements
+- `insertBefore(selector)`, `insertAfter(selector)` - Insert elements relative to targets
 
 ### Attribute/Property Management
 - `attr(name)`, `attr(name, value)` - Get/set attributes
 - `removeAttr(name)` - Remove attributes
 - `prop(name)`, `prop(name, value)` - Get/set properties
-- `data(key)`, `data(key, value)` - Get/set data attributes
 
 ### CSS and Styling
 - `css(property)`, `css(property, value)` - Get/set CSS properties
-- `addClass()`, `removeClass()`, `toggleClass()` - Manage CSS classes
-- `hasClass()` - Check for CSS class
-- `show()`, `hide()` - Show/hide elements
+- `cssVar(variable, value)` - Get/set CSS custom properties
+- `computedStyle(property)` - Get computed styles
+- `addClass(classes)`, `removeClass(classes)`, `toggleClass(classes)` - Manage CSS classes
+- `hasClass(className)` - Check for CSS class
 
 ### Event Handling
 - `on(event, selector, handler)` - Event delegation
 - `off(event, handler)` - Remove event listeners
-- `trigger(event, data)` - Trigger custom events
+- `trigger(event, data)` - Trigger events
+- `dispatchEvent(event, data, settings)` - Dispatch custom events
 - `one(event, handler)` - One-time event listener
 
 ### Dimensions and Positioning
-- `width()`, `height()` - Get/set dimensions
-- `innerWidth()`, `outerWidth()` - Get calculated dimensions
-- `offset()`, `position()` - Get element positioning
-- `scrollTop()`, `scrollLeft()` - Get/set scroll position
+- `width(value)`, `height(value)` - Get/set dimensions
+- `scrollWidth(value)`, `scrollHeight(value)` - Get/set scroll dimensions
+- `scrollTop(value)`, `scrollLeft(value)` - Get/set scroll position
+- `offsetParent(options)` - Get offset parent for positioning
+- `naturalWidth()`, `naturalHeight()` - Get natural dimensions
 
 ### Component Integration (Semantic UI specific)
 - `settings(newSettings)` - Configure component settings
+- `setting(name, value)` - Get/set individual component settings
 - `initialize(settings)` - Initialize component before DOM insertion
-- `component()` - Get component template instance
+- `component()` - Get component instance
 - `dataContext()` - Get component's data context for debugging
 
 ## Component-Aware Methods
@@ -321,14 +348,13 @@ $('document').on('keydown', function(event) {
 ### Method Chaining
 
 ```javascript
-// jQuery-style chaining
+// Query-style chaining
 $('.items')
   .addClass('processed')
   .find('.button')
   .on('click', handleClick)
   .css('color', 'blue')
-  .end()                    // Return to previous selection (.items)
-  .fadeIn();
+  .end();                   // Return to previous selection (.items)
 ```
 
 ### Iteration and Filtering
@@ -357,9 +383,9 @@ $('.item').filter(function(index, element) {
 $('.title').text('New Title');
 $('.container').html('<p>New content</p>');
 
-// Data attributes
-$('.item').data('id', 123);
-const itemId = $('.item').data('id');
+// HTML data attributes via attr()
+$('.item').attr('data-id', '123');
+const itemId = $('.item').attr('data-id');
 
 // Form values
 $('input[name="email"]').val('user@example.com');
diff --git a/ai/specialized/reactivity-system-guide.md b/ai/packages/reactivity.md
similarity index 100%
rename from ai/specialized/reactivity-system-guide.md
rename to ai/packages/reactivity.md
diff --git a/ai/specialized/templating-system-guide.md b/ai/packages/templating.md
similarity index 100%
rename from ai/specialized/templating-system-guide.md
rename to ai/packages/templating.md
diff --git a/ai/specialized/utils-package-guide.md b/ai/packages/utils.md
similarity index 100%
rename from ai/specialized/utils-package-guide.md
rename to ai/packages/utils.md
diff --git a/ai/proposals/animations.js b/ai/proposals/animations.js
new file mode 100644
index 000000000..fc75a1dd5
--- /dev/null
+++ b/ai/proposals/animations.js
@@ -0,0 +1,287 @@
+/**
+ * Reusable keyframe objects. Stored as constants so they are defined only once
+ * and can be referenced by multiple animation definitions. This is ideal for
+ * both DRY principles and minification.
+ */
+const slideInY = {
+  '0%': { opacity: 0, transform: 'scaleY(0)' },
+  '100%': { opacity: 1, transform: 'scaleY(1)' }
+};
+const slideOutY = {
+  '0%': { opacity: 1, transform: 'scaleY(1)' },
+  '100%': { opacity: 0, transform: 'scaleY(0)' }
+};
+const slideInX = {
+  '0%': { opacity: 0, transform: 'scaleX(0)' },
+  '100%': { opacity: 1, transform: 'scaleX(1)' }
+};
+const slideOutX = {
+  '0%': { opacity: 1, transform: 'scaleX(1)' },
+  '100%': { opacity: 0, transform: 'scaleX(0)' }
+};
+
+const swingInX = {
+  '0%': { transform: 'perspective(1000px) rotateX(90deg)', opacity: 0 },
+  '40%': { transform: 'perspective(1000px) rotateX(-30deg)', opacity: 1 },
+  '60%': { transform: 'perspective(1000px) rotateX(15deg)' },
+  '80%': { transform: 'perspective(1000px) rotateX(-7.5deg)' },
+  '100%': { transform: 'perspective(1000px) rotateX(0deg)' }
+};
+const swingOutX = {
+  '0%': { transform: 'perspective(1000px) rotateX(0deg)' },
+  '40%': { transform: 'perspective(1000px) rotateX(-7.5deg)' },
+  '60%': { transform: 'perspective(1000px) rotateX(17.5deg)' },
+  '80%': { transform: 'perspective(1000px) rotateX(-30deg)', opacity: 1 },
+  '100%': { transform: 'perspective(1000px) rotateX(90deg)', opacity: 0 }
+};
+const swingInY = {
+  '0%': { transform: 'perspective(1000px) rotateY(-90deg)', opacity: 0 },
+  '40%': { transform: 'perspective(1000px) rotateY(30deg)', opacity: 1 },
+  '60%': { transform: 'perspective(1000px) rotateY(-17.5deg)' },
+  '80%': { transform: 'perspective(1000px) rotateY(7.5deg)' },
+  '100%': { transform: 'perspective(1000px) rotateY(0deg)' }
+};
+const swingOutY = {
+  '0%': { transform: 'perspective(1000px) rotateY(0deg)' },
+  '40%': { transform: 'perspective(1000px) rotateY(7.5deg)' },
+  '60%': { transform: 'perspective(1000px) rotateY(-10deg)' },
+  '80%': { transform: 'perspective(1000px) rotateY(30deg)', opacity: 1 },
+  '100%': { transform: 'perspective(1000px) rotateY(-90deg)', opacity: 0 }
+};
+
+
+/**
+ * The main animation definitions, structured as JS objects for optimal minification.
+ * - `keyframe`: A direct reference to one of the reusable keyframe objects above.
+ * - `keyframeName`: A string to name the animation. This is used when the keyframe is unique.
+ * - `alias`: Points to another definition path within this object to avoid repetition.
+ */
+const animationDefinitions = {
+  browse: {
+    in: {
+      duration: '500ms',
+      keyframeName: 'browseIn',
+      keyframe: {
+        '0%': { transform: 'scale(0.8) translateZ(0px)', zIndex: -1 },
+        '10%': { transform: 'scale(0.8) translateZ(0px)', zIndex: -1, opacity: 0.7 },
+        '80%': { transform: 'scale(1.05) translateZ(0px)', opacity: 1, zIndex: 999 },
+        '100%': { transform: 'scale(1) translateZ(0px)', zIndex: 999 }
+      }
+    },
+    out: {
+      duration: '500ms',
+      keyframeName: 'browseOutLeft',
+      keyframe: {
+        '0%': { zIndex: 999, transform: 'translateX(0%) rotateY(0deg) rotateX(0deg)' },
+        '50%': { zIndex: -1, transform: 'translateX(-105%) rotateY(35deg) rotateX(10deg) translateZ(-10px)' },
+        '80%': { opacity: 1 },
+        '100%': { zIndex: -1, transform: 'translateX(0%) rotateY(0deg) rotateX(0deg) translateZ(-10px)', opacity: 0 }
+      }
+    },
+    right: {
+      out: {
+        duration: '500ms',
+        keyframeName: 'browseOutRight',
+        keyframe: {
+          '0%': { zIndex: 999, transform: 'translateX(0%) rotateY(0deg) rotateX(0deg)' },
+          '50%': { zIndex: 1, transform: 'translateX(105%) rotateY(35deg) rotateX(10deg) translateZ(-10px)' },
+          '80%': { opacity: 1 },
+          '100%': { zIndex: 1, transform: 'translateX(0%) rotateY(0deg) rotateX(0deg) translateZ(-10px)', opacity: 0 }
+        }
+      }
+    }
+  },
+
+  drop: {
+    in: {
+      duration: '400ms',
+      keyframeName: 'dropIn',
+      keyframe: {
+        '0%': { opacity: 0, transform: 'scale(0)' },
+        '100%': { opacity: 1, transform: 'scale(1)' }
+      }
+    },
+    out: {
+      duration: '400ms',
+      keyframeName: 'dropOut',
+      keyframe: {
+        '0%': { opacity: 1, transform: 'scale(1)' },
+        '100%': { opacity: 0, transform: 'scale(0)' }
+      }
+    }
+  },
+
+  fade: {
+    in: { duration: '300ms', keyframeName: 'fadeIn', keyframe: { '0%': { opacity: 0 }, '100%': { opacity: 1 } } },
+    out: { duration: '300ms', keyframeName: 'fadeOut', keyframe: { '0%': { opacity: 1 }, '100%': { opacity: 0 } } },
+    up: {
+      in: { keyframeName: 'fadeInUp', keyframe: { '0%': { opacity: 0, transform: 'translateY(10%)' }, '100%': { opacity: 1, transform: 'translateY(0%)' } } },
+      out: { keyframeName: 'fadeOutUp', keyframe: { '0%': { opacity: 1, transform: 'translateY(0%)' }, '100%': { opacity: 0, transform: 'translateY(5%)' } } }
+    },
+    down: {
+      in: { keyframeName: 'fadeInDown', keyframe: { '0%': { opacity: 0, transform: 'translateY(-10%)' }, '100%': { opacity: 1, transform: 'translateY(0%)' } } },
+      out: { keyframeName: 'fadeOutDown', keyframe: { '0%': { opacity: 1, transform: 'translateY(0%)' }, '100%': { opacity: 0, transform: 'translateY(-5%)' } } }
+    },
+    left: {
+      in: { keyframeName: 'fadeInLeft', keyframe: { '0%': { opacity: 0, transform: 'translateX(10%)' }, '100%': { opacity: 1, transform: 'translateX(0%)' } } },
+      out: { keyframeName: 'fadeOutLeft', keyframe: { '0%': { opacity: 1, transform: 'translateX(0%)' }, '100%': { opacity: 0, transform: 'translateX(5%)' } } }
+    },
+    right: {
+      in: { keyframeName: 'fadeInRight', keyframe: { '0%': { opacity: 0, transform: 'translateX(-10%)' }, '100%': { opacity: 1, transform: 'translateX(0%)' } } },
+      out: { keyframeName: 'fadeOutRight', keyframe: { '0%': { opacity: 1, transform: 'translateX(0%)' }, '100%': { opacity: 0, transform: 'translateX(-5%)' } } }
+    }
+  },
+
+  fly: {
+    duration: '600ms',
+    in: { keyframeName: 'flyIn', keyframe: { '0%':{opacity:0,transform:'scale3d(.3,.3,.3)'},'20%':{transform:'scale3d(1.1,1.1,1.1)'},'40%':{transform:'scale3d(.9,.9,.9)'},'60%':{opacity:1,transform:'scale3d(1.03,1.03,1.03)'},'80%':{transform:'scale3d(.97,.97,.97)'},'100%':{opacity:1,transform:'scale3d(1,1,1)'} } },
+    out: { keyframeName: 'flyOut', keyframe: { '20%':{transform:'scale3d(.9,.9,.9)'},'50%,55%':{opacity:1,transform:'scale3d(1.1,1.1,1.1)'},'100%':{opacity:0,transform:'scale3d(.3,.3,.3)'} } },
+    up: {
+      in: { keyframeName: 'flyInUp', keyframe: { '0%':{opacity:0,transform:'translate3d(0,1500px,0)'},'60%':{opacity:1,transform:'translate3d(0,-20px,0)'},'75%':{transform:'translate3d(0,10px,0)'},'90%':{transform:'translate3d(0,-5px,0)'},'100%':{transform:'translate3d(0,0,0)'} } },
+      out: { keyframeName: 'flyOutUp', keyframe: { '20%':{transform:'translate3d(0,10px,0)'},'40%,45%':{opacity:1,transform:'translate3d(0,-20px,0)'},'100%':{opacity:0,transform:'translate3d(0,2000px,0)'} } }
+    },
+    down: {
+      in: { keyframeName: 'flyInDown', keyframe: { '0%':{opacity:0,transform:'translate3d(0,-1500px,0)'},'60%':{opacity:1,transform:'translate3d(0,25px,0)'},'75%':{transform:'translate3d(0,-10px,0)'},'90%':{transform:'translate3d(0,5px,0)'},'100%':{transform:'none'} } },
+      out: { keyframeName: 'flyOutDown', keyframe: { '20%':{transform:'translate3d(0,-10px,0)'},'40%,45%':{opacity:1,transform:'translate3d(0,20px,0)'},'100%':{opacity:0,transform:'translate3d(0,-2000px,0)'} } }
+    },
+    left: {
+      in: { keyframeName: 'flyInLeft', keyframe: { '0%':{opacity:0,transform:'translate3d(1500px,0,0)'},'60%':{opacity:1,transform:'translate3d(-25px,0,0)'},'75%':{transform:'translate3d(10px,0,0)'},'90%':{transform:'translate3d(-5px,0,0)'},'100%':{transform:'none'} } },
+      out: { keyframeName: 'flyOutLeft', keyframe: { '20%':{opacity:1,transform:'translate3d(-20px,0,0)'},'100%':{opacity:0,transform:'translate3d(2000px,0,0)'} } }
+    },
+    right: {
+      in: { keyframeName: 'flyInRight', keyframe: { '0%':{opacity:0,transform:'translate3d(-1500px,0,0)'},'60%':{opacity:1,transform:'translate3d(25px,0,0)'},'75%':{transform:'translate3d(-10px,0,0)'},'90%':{transform:'translate3d(5px,0,0)'},'100%':{transform:'none'} } },
+      out: { keyframeName: 'flyOutRight', keyframe: { '20%':{opacity:1,transform:'translate3d(20px,0,0)'},'100%':{opacity:0,transform:'translate3d(-2000px,0,0)'} } }
+    }
+  },
+
+  flip: {
+    duration: '600ms',
+    horizontal: {
+      in: { keyframeName: 'horizontalFlipIn', keyframe: { '0%':{transform:'perspective(2000px) rotateY(-90deg)',opacity:0},'100%':{transform:'perspective(2000px) rotateY(0)',opacity:1} } },
+      out: { keyframeName: 'horizontalFlipOut', keyframe: { '0%':{transform:'perspective(2000px) rotateY(0)',opacity:1},'100%':{transform:'perspective(2000px) rotateY(90deg)',opacity:0} } }
+    },
+    vertical: {
+      in: { keyframeName: 'verticalFlipIn', keyframe: { '0%':{transform:'perspective(2000px) rotateX(-90deg)',opacity:0},'100%':{transform:'perspective(2000px) rotateX(0)',opacity:1} } },
+      out: { keyframeName: 'verticalFlipOut', keyframe: { '0%':{transform:'perspective(2000px) rotateX(0)',opacity:1},'100%':{transform:'perspective(2000px) rotateX(-90deg)',opacity:0} } }
+    }
+  },
+
+  scale: {
+    in: { duration: '300ms', keyframeName: 'scaleIn', keyframe: { '0%': { opacity: 0, transform: 'scale(0.8)' }, '100%': { opacity: 1, transform: 'scale(1)' } } },
+    out: { duration: '300ms', keyframeName: 'scaleOut', keyframe: { '0%': { opacity: 1, transform: 'scale(1)' }, '100%': { opacity: 0, transform: 'scale(0.9)' } } }
+  },
+
+  slide: {
+    down: {
+      in: { keyframeName: 'slideInY', keyframe: slideInY },
+      out: { keyframeName: 'slideOutY', keyframe: slideOutY }
+    },
+    up: { alias: 'slide.down' },
+    left: {
+      in: { keyframeName: 'slideInX', keyframe: slideInX },
+      out: { keyframeName: 'slideOutX', keyframe: slideOutX }
+    },
+    right: { alias: 'slide.left' }
+  },
+
+  swing: {
+    duration: '800ms',
+    down: {
+      in: { keyframeName: 'swingInX', keyframe: swingInX },
+      out: { keyframeName: 'swingOutX', keyframe: swingOutX }
+    },
+    up: { alias: 'swing.down' },
+    left: {
+      in: { keyframeName: 'swingInY', keyframe: swingInY },
+      out: { keyframeName: 'swingOutY', keyframe: swingOutY }
+    },
+    right: { alias: 'swing.left' }
+  },
+
+  zoom: {
+    in: { keyframeName: 'zoomIn', keyframe: { '0%':{opacity:1,transform:'scale(0)'},'100%':{opacity:1,transform:'scale(1)'} } },
+    out: { keyframeName: 'zoomOut', keyframe: { '0%':{opacity:1,transform:'scale(1)'},'100%':{opacity:1,transform:'scale(0)'} } }
+  },
+
+
+  // --- Static Animations (no in/out direction) ---
+  jiggle: {
+    static: {
+      duration: '750ms',
+      keyframeName: 'jiggle',
+      keyframe: {
+        '0%': { transform: 'scale3d(1, 1, 1)' },
+        '30%': { transform: 'scale3d(1.25, 0.75, 1)' },
+        '40%': { transform: 'scale3d(0.75, 1.25, 1)' },
+        '50%': { transform: 'scale3d(1.15, 0.85, 1)' },
+        '65%': { transform: 'scale3d(0.95, 1.05, 1)' },
+        '75%': { transform: 'scale3d(1.05, 0.95, 1)' },
+        '100%': { transform: 'scale3d(1, 1, 1)' }
+      }
+    }
+  },
+  flash: {
+    static: {
+      duration: '750ms',
+      keyframeName: 'flash',
+      keyframe: { '0%, 50%, 100%': { opacity: 1 }, '25%, 75%': { opacity: 0 } }
+    }
+  },
+  shake: {
+    static: {
+      duration: '750ms',
+      keyframeName: 'shake',
+      keyframe: {
+        '0%, 100%': { transform: 'translateX(0)' },
+        '10%, 30%, 50%, 70%, 90%': { transform: 'translateX(-10px)' },
+        '20%, 40%, 60%, 80%': { transform: 'translateX(10px)' }
+      }
+    }
+  },
+  bounce: {
+    static: {
+      duration: '750ms',
+      keyframeName: 'bounce',
+      keyframe: {
+        '0%, 20%, 50%, 80%, 100%': { transform: 'translateY(0)' },
+        '40%': { transform: 'translateY(-30px)' },
+        '60%': { transform: 'translateY(-15px)' }
+      }
+    }
+  },
+  tada: {
+    static: {
+      duration: '750ms',
+      keyframeName: 'tada',
+      keyframe: {
+        '0%': { transform: 'scale(1)' },
+        '10%, 20%': { transform: 'scale(0.9) rotate(-3deg)' },
+        '30%, 50%, 70%, 90%': { transform: 'scale(1.1) rotate(3deg)' },
+        '40%, 60%, 80%': { transform: 'scale(1.1) rotate(-3deg)' },
+        '100%': { transform: 'scale(1) rotate(0)' }
+      }
+    }
+  },
+  pulse: {
+    static: {
+      duration: '500ms',
+      keyframeName: 'pulse',
+      keyframe: {
+        '0%': { transform: 'scale(1)', opacity: 1 },
+        '50%': { transform: 'scale(0.9)', opacity: 0.7 },
+        '100%': { transform: 'scale(1)', opacity: 1 }
+      }
+    }
+  },
+  glow: {
+    static: {
+      duration: '2000ms',
+      keyframeName: 'glow',
+      keyframe: {
+        '0%': { backgroundColor: '#FCFCFD' },
+        '30%': { backgroundColor: '#FFF6CD' },
+        '100%': { backgroundColor: '#FCFCFD' }
+      }
+    }
+  }
+};
diff --git a/ai/proposals/query-core-missing-methods.md b/ai/proposals/query-core-missing-methods.md
new file mode 100644
index 000000000..301160984
--- /dev/null
+++ b/ai/proposals/query-core-missing-methods.md
@@ -0,0 +1,100 @@
+# Query Core - Missing Methods Proposal
+
+> **Scope:** Essential missing methods with minimal complexity  
+> **Status:** Draft for implementation  
+> **Size Impact:** Minimal - mostly aliases and simple logic reuse
+
+---
+
+## Array-like Operations
+
+### `slice(start, end)`
+Get subset of elements as new Query instance.
+
+- `start` - Number starting index
+- `end` - Number ending index (optional)
+
+**Implementation:** Simple Array.slice() wrapper
+
+### `splice(start, deleteCount, ...items)`
+Modify the element collection in place.
+
+- `start` - Number starting index  
+- `deleteCount` - Number of elements to remove
+- `items` - Elements to insert at start position
+
+**Implementation:** Array.splice() with Query wrapping
+
+---
+
+## Enhanced Traversal
+
+~~Enhanced traversal removed from core scope - `parents()` not commonly needed in practice~~
+
+---
+
+## DOM Insertion Aliases
+
+### `before(content)`
+Alias for `insertBefore()` with more intuitive name.
+
+- `content` - String HTML | Element | Query | Array of content
+
+**Implementation:** Simple alias to existing insertBefore logic
+
+### `after(content)`  
+Alias for `insertAfter()` with more intuitive name.
+
+- `content` - String HTML | Element | Query | Array of content
+
+**Implementation:** Simple alias to existing insertAfter logic
+
+---
+
+## Enhanced Dimensions
+
+### `width(options)` / `height(options)`
+Extend existing methods with inclusion options.
+
+- `options.includeMargin` - Boolean to include margin
+- `options.includePadding` - Boolean to include padding  
+- `options.includeBorder` - Boolean to include border
+
+**Implementation:** Extend existing width/height with computed style calculations
+
+---
+
+## Data Attribute Helpers
+
+### `data(key, value)`
+Get/set data-* attributes with type conversion.
+
+- `key` - String attribute name or Object of key-value pairs
+- `value` - Any value to set, undefined to get
+
+**Implementation:** Wrapper around attr() with 'data-' prefix and JSON parsing
+
+### `data()`
+Get all data-* attributes as object.
+
+**Implementation:** Filter attributes starting with 'data-', parse values
+
+---
+
+## Shadow DOM Enhancements
+
+### `contains(selector)`
+Check if elements contain targets. Automatically shadow DOM aware based on `this.options.pierceShadow`.
+
+- `selector` - String | Element | Query to check containment
+
+**Implementation:** Use DOM `.contains()` or deep traversal based on `this.options.pierceShadow`
+
+---
+
+## Implementation Notes
+
+- **File size impact:** < 1.5KB gzipped  
+- **Complexity:** Very low - mostly aliases and simple extensions
+- **Dependencies:** None - uses existing Query infrastructure
+- **Breaking changes:** None - all additions
\ No newline at end of file
diff --git a/ai/proposals/query-css-animations.md b/ai/proposals/query-css-animations.md
new file mode 100644
index 000000000..033f8ddb0
--- /dev/null
+++ b/ai/proposals/query-css-animations.md
@@ -0,0 +1,135 @@
+# Query CSS Animations Extension
+
+> **Scope:** CSS-based animations and transitions integration  
+> **Status:** Complex scope requiring design decisions  
+> **Size Impact:** Moderate - style injection and state management logic
+
+---
+
+## Core Animation Methods
+
+### `show(options)`
+Show elements with CSS animation support.
+
+- `options.animation` - String CSS animation class or transition property
+- `options.duration` - String CSS duration ('300ms', '0.3s')
+- `options.timing` - String CSS timing function ('ease', 'cubic-bezier(...)')
+- `options.display` - String target display value ('block', 'flex', 'inline-block')
+
+### `hide(options)`
+Hide elements with CSS animation support.
+
+- `options.animation` - String CSS animation class or transition property  
+- `options.duration` - String CSS duration
+- `options.timing` - String CSS timing function
+
+### `toggle(force, options)`
+Toggle visibility with animation support.
+
+- `force` - Boolean to force show/hide, undefined for toggle
+- `options` - Same as show/hide options
+
+### `visible()`
+Check if elements are visible.
+
+**Returns:** Boolean true if any element is visible
+
+---
+
+## Design Challenges
+
+### Display State Resolution
+**Problem:** When showing `display: none` elements, what should the final display value be?
+
+**Options:**
+1. **Store original display** - Remember pre-hide display value
+2. **Compute from CSS** - Analyze stylesheets for intended display  
+3. **Default + override** - Default to 'block', allow explicit override
+4. **Element-based heuristics** - div=block, span=inline, etc.
+
+### Style Injection Strategy
+**Problem:** How to inject temporary animation styles?
+
+**Options:**
+1. **Inline styles** - Direct element.style modification
+2. **Style sheet injection** - Dynamic `<style>` elements  
+3. **CSS class toggle** - Predefined animation classes
+4. **CSS custom properties** - Inject CSS variables
+
+### Animation Completion Detection
+**Problem:** How to detect when animations finish?
+
+**Options:**
+1. **Event listeners** - animationend/transitionend events
+2. **Timeout fallback** - setTimeout based on duration
+3. **Promise-based** - Return promises for animation completion
+4. **Callback support** - Traditional callback patterns
+
+---
+
+## Recommended Approach
+
+### Phase 1: Basic Implementation
+```javascript
+// Simple class-based animations
+$('.modal').show({ animation: 'fadeIn', duration: '300ms' });
+
+// Implementation:
+// 1. Store current display value  
+// 2. Add animation class
+// 3. Set display to target value
+// 4. Listen for animationend
+// 5. Clean up animation class
+```
+
+### Phase 2: Advanced Features  
+```javascript
+// Custom animations with style injection
+$('.panel').show({
+  animation: {
+    keyframes: '0% { opacity: 0; } 100% { opacity: 1; }',
+    duration: '400ms',
+    timing: 'ease-out'
+  },
+  display: 'flex'
+});
+```
+
+---
+
+## Implementation Complexity
+
+### High Complexity Areas
+- **Cross-browser animation events** - Different event names and behaviors
+- **Style cascade handling** - Ensuring animations don't conflict with existing styles  
+- **Memory management** - Cleaning up injected styles and event listeners
+- **Shadow DOM integration** - Style injection across shadow boundaries
+
+### Medium Complexity Areas
+- **Display state management** - Storing and restoring display values
+- **Animation queuing** - Handling multiple animations on same element
+- **Error handling** - Graceful degradation when animations fail
+
+### File Size Impact
+- **Estimated:** 3-5KB gzipped for full implementation
+- **Core features only:** 1-2KB gzipped
+
+---
+
+## Alternative: Plugin Architecture First
+
+Given the complexity, this might be better suited as the first major plugin rather than core functionality. This would:
+
+1. **Validate plugin system** - Real-world test of plugin architecture
+2. **Keep core lean** - Animations are not essential for DOM manipulation
+3. **Allow experimentation** - Easier to iterate on API design
+4. **Optional inclusion** - Developers import only if needed
+
+```javascript
+// As plugin
+import { $ } from '@semantic-ui/query';
+import { animations } from '@semantic-ui/query/plugins/animations';
+
+$.use(animations);
+$('.modal').show({ animation: 'fadeIn' });
+```
\ No newline at end of file
diff --git a/ai/proposals/query-missing-methods.md b/ai/proposals/query-missing-methods.md
new file mode 100644
index 000000000..b2b944584
--- /dev/null
+++ b/ai/proposals/query-missing-methods.md
@@ -0,0 +1,203 @@
+# Query Package - Missing Methods Proposal
+
+> **For:** Framework review and implementation planning  
+> **Status:** Draft for discussion  
+> **Context:** Based on analysis of existing Query implementation vs jQuery-like expectations
+
+---
+
+## High Priority - Modern Positioning
+
+### `position(target, options)`
+Modern positioning with Shadow DOM and viewport awareness, inspired by floating-ui.
+
+- `target` - Element | Query | selector to position relative to
+- `options.placement` - 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'bottom-end' etc.
+- `options.middleware` - Array of positioning adjustments ['flip', 'shift', 'offset', 'arrow']
+- `options.boundary` - Element | 'viewport' | 'clippingAncestors' for collision detection
+- `options.offset` - Number | {mainAxis, crossAxis} for positioning offset
+- `options.crossShadow` - Boolean to handle shadow DOM boundary calculations
+
+**Returns:** Query instance for chaining
+
+### `getBounds(options)`
+Get comprehensive position/size data with Shadow DOM awareness.
+
+- `options.relative` - Element | 'viewport' | 'offset-parent' for coordinate system
+- `options.includeBorder` - Boolean to include border in calculations
+- `options.includeMargin` - Boolean to include margin in calculations
+
+**Returns:** Object with {x, y, width, height, top, left, right, bottom, viewport: {...}}
+
+---
+
+## High Priority - Enhanced Traversal
+
+### `parents(selector)`
+Get all ancestor elements, optionally filtered by selector.
+
+- `selector` - String CSS selector to filter ancestors (optional)
+
+**Returns:** Query instance with ancestor elements
+
+### `end()`
+Return to the previous set of elements in the chain.
+
+**Returns:** Query instance from prevObject or current instance
+
+---
+
+## High Priority - Data Attribute Helpers
+
+### `data(key, value)`
+Get/set data-* attributes with automatic type conversion.
+
+- `key` - String attribute name (without 'data-' prefix) or Object of key-value pairs
+- `value` - Any value to set (auto-stringified), undefined to get
+
+**Returns:** Value when getting, Query instance when setting
+
+### `data()`
+Get all data-* attributes as an object.
+
+**Returns:** Object with all data attributes (keys without 'data-' prefix)
+
+---
+
+## High Priority - Intuitive DOM Insertion
+
+### `before(content)`
+Insert content before each element.
+
+- `content` - String HTML | Element | Query | Array of content to insert
+
+**Returns:** Query instance for chaining
+
+### `after(content)` 
+Insert content after each element.
+
+- `content` - String HTML | Element | Query | Array of content to insert
+
+**Returns:** Query instance for chaining
+
+---
+
+## Medium Priority - Enhanced Dimensions
+
+### `innerWidth(value)`
+Get/set width including padding, excluding border.
+
+- `value` - Number to set width (optional)
+
+**Returns:** Number when getting, Query instance when setting
+
+### `innerHeight(value)`
+Get/set height including padding, excluding border.
+
+- `value` - Number to set height (optional)
+
+**Returns:** Number when getting, Query instance when setting
+
+### `outerWidth(includeMargin, value)`
+Get/set width including padding and border, optionally margin.
+
+- `includeMargin` - Boolean to include margin in calculation
+- `value` - Number to set width (optional)
+
+**Returns:** Number when getting, Query instance when setting
+
+### `outerHeight(includeMargin, value)`
+Get/set height including padding and border, optionally margin.
+
+- `includeMargin` - Boolean to include margin in calculation  
+- `value` - Number to set height (optional)
+
+**Returns:** Number when getting, Query instance when setting
+
+---
+
+## Medium Priority - Modern Visibility
+
+### `show(options)`
+Show elements with optional CSS animation integration.
+
+- `options.animation` - String CSS animation name or transition
+- `options.duration` - String CSS duration value  
+- `options.timing` - String CSS timing function
+
+**Returns:** Query instance for chaining
+
+### `hide(options)`
+Hide elements with optional CSS animation integration.
+
+- `options.animation` - String CSS animation name or transition
+- `options.duration` - String CSS duration value
+- `options.timing` - String CSS timing function  
+
+**Returns:** Query instance for chaining
+
+### `toggle(force)`
+Toggle element visibility.
+
+- `force` - Boolean to force show (true) or hide (false), undefined for toggle
+
+**Returns:** Query instance for chaining
+
+### `visible()`
+Check if elements are visible (not display:none, visibility:hidden, or 0 opacity).
+
+**Returns:** Boolean true if any element is visible
+
+---
+
+## Shadow DOM Specific Enhancements
+
+### `positionRelativeTo(target, options)`
+Position elements relative to target across Shadow DOM boundaries.
+
+- `target` - Element | Query | selector within any shadow context
+- `options.placement` - String placement relative to target
+- `options.boundary` - Element | 'shadow-root' | 'viewport' for boundary detection
+- `options.middleware` - Array of adjustments for shadow DOM contexts
+
+**Returns:** Query instance for chaining
+
+### `contains(selector)`
+Check if elements contain other elements, crossing shadow boundaries when using $$.
+
+- `selector` - String | Element | Query to check containment
+
+**Returns:** Boolean true if any element contains the target
+
+---
+
+## Low Priority - Array-like Operations
+
+### `slice(start, end)`
+Get subset of elements as new Query instance.
+
+- `start` - Number starting index
+- `end` - Number ending index (optional)
+
+**Returns:** Query instance with sliced elements
+
+
+---
+
+## Implementation Notes
+
+### Positioning Priority
+The positioning methods (`position`, `getBounds`, `positionRelativeTo`) address the most complex challenges in modern web component environments and would provide significant value for dropdown, modal, tooltip, and overlay positioning.
+
+### Shadow DOM Considerations
+All traversal and positioning methods should be shadow DOM aware when used with `$$` prefix, maintaining the dual-mode philosophy of the Query system.
+
+### Performance Impact
+Data attribute methods and enhanced dimensions have minimal performance impact. Positioning methods require more computation but solve complex problems that would otherwise need external libraries.
+
+### API Consistency
+All methods follow existing Query patterns:
+- Chainable when setting/modifying
+- Return values when getting
+- Accept same input types as existing methods
+- Use options objects for complex configuration
diff --git a/ai/proposals/query-plugin.md b/ai/proposals/query-plugin.md
new file mode 100644
index 000000000..25dd2383e
--- /dev/null
+++ b/ai/proposals/query-plugin.md
@@ -0,0 +1,79 @@
+# Proposal: A Hybrid Plugin Architecture for `@semantic-ui/query`
+
+## 1. Goal: A Robust Plugin Ecosystem
+
+The primary goal is to establish a formal plugin architecture for the `@semantic-ui/query` package. This architecture must empower third-party developers to extend the library's functionality in a consistent, stable, and easy-to-use manner. It should codify the best practices learned from the Semantic UI module system into the core library, reducing boilerplate and encouraging community contribution.
+
+## 2. Architectural Strategy: A Hybrid Approach
+
+To maximize both flexibility and developer experience, a hybrid, dual-layer architectural strategy is proposed. This provides two distinct pathways for plugin registration, catering to different needs.
+
+### Layer 1: The Unmanaged, Low-Level API (`$.fn`)
+
+This layer provides a direct, unmanaged entry point to the `Query` prototype.
+
+* **Strategy**: Expose the `Query.prototype` through a conventional alias (`$.fn` and `$$.fn`). This is a classic pattern, offering an immediate "escape hatch" for developers who need complete control or are familiar with the jQuery ecosystem.
+* **Use Case**: Ideal for simple, stateless plugins or for porting existing jQuery plugins with minimal changes.
+* **Responsibility**: The library's only responsibility is to provide the alias. The plugin author is fully responsible for all implementation details, including state management, settings parsing, and method invocation logic.
+* **Benefit**: Maximum flexibility and a zero-friction entry point for experienced developers.
+
+**Example of the `$.fn` Strategy in Use:**
+```javascript
+import { $ } from '@semantic-ui/query';
+
+// The author implements all logic, including chaining.
+$.fn.makeGreen = function() {
+  this.each(instance => {
+    instance.elements[0].style.color = 'green';
+  });
+  return this;
+};
+```
+
+### Layer 2: The Managed, High-Level API (`registerPlugin`)
+
+This layer provides an opinionated, "blessed" API for creating complex plugins. It is the recommended approach for building robust, stateful modules for the ecosystem.
+
+* **Strategy**: Export a single `registerPlugin(name, definition)` function. This function acts as a factory that takes a simple plugin definition object and wraps it in all the necessary boilerplate logic (instance management, method dispatching, etc.). This abstracts the complex patterns from Semantic UI's module system into the core.
+* **The Plugin Contract**: The plugin author's responsibility is reduced to providing a simple `definition` object that adheres to a clear contract:
+    * `defaults`: An object defining the default settings for the plugin.
+    * `methods`: An object containing the core logic as functions. This includes a special `init` method for initialization logic.
+* **The Library's Responsibilities**: The `registerPlugin` function will automatically handle the following for the plugin author:
+    * **Method Dispatching**: It creates and attaches a single function to the prototype (`Query.prototype[name]`) that intelligently distinguishes between calls for initialization (e.g., `$('...').myPlugin({})`) and calls to public methods (e.g., `$('...').myPlugin('myMethod', arg1)`).
+    * **Instance Management**: It transparently manages the lifecycle of a plugin instance for each DOM element. It handles creating, storing, retrieving, and (if a `destroy` method is provided) cleaning up instances. State is stored per-element, not globally.
+    * **Context Provisioning**: For every method in the `methods` object, it ensures `this` refers to a dedicated instance object. This context object will be automatically populated with:
+        * `this.settings`: The final, merged settings (defaults + user-provided).
+        * `this.element`: The raw DOM element the instance is attached to.
+        * `this.queryInstance`: The `Query` object for that element.
+        * `this.name`: The name of the plugin.
+    * **Lifecycle Hooks**: It automatically invokes the `init` method from the plugin definition when a new instance is created.
+* **Benefit**: Drastically simplifies plugin development, enforces consistency across the ecosystem, and makes plugins easier to maintain by separating core logic from boilerplate.
+
+**Example of the `registerPlugin` Strategy in Use:**
+```javascript
+import { registerPlugin } from '@semantic-ui/query';
+
+// The author only provides the unique logic.
+registerPlugin('myCoolPlugin', {
+  defaults: {
+    color: 'blue',
+    speed: 400
+  },
+  methods: {
+    init: function() {
+      // The library provides `this.settings` and `this.element`.
+      this.element.style.color = this.settings.color;
+    },
+    show: function() {
+      // Logic for showing the element...
+    },
+    hide: function() {
+      // Logic for hiding the element...
+    }
+  }
+});
+```
+
+## 4. Conclusion
+
+By adopting this hybrid architecture, `@semantic-ui/query` can offer a plugin system that is both powerfully simple for the majority of use cases (`registerPlugin`) and endlessly flexible for advanced scenarios (`$.fn`). This provides a clear path for building a rich and consistent component ecosystem.
diff --git a/ai/proposals/query-positioning-revised.md b/ai/proposals/query-positioning-revised.md
new file mode 100644
index 000000000..738885f5c
--- /dev/null
+++ b/ai/proposals/query-positioning-revised.md
@@ -0,0 +1,195 @@
+# Query Positioning System - Revised Proposal
+
+> **Scope:** Essential positioning with Semantic UI-level collision detection  
+> **Status:** Based on original SUI popup collision logic analysis  
+> **Size Impact:** 4-6KB gzipped for comprehensive positioning
+
+---
+
+## Core Positioning API
+
+### `position(target, options)`
+Position elements relative to target with collision detection.
+
+- `target` - Element | Query | selector to position relative to
+- `options.placement` - String placement ('top', 'bottom', 'left', 'right', 'top-start', 'bottom-end', etc.)
+- `options.strategy` - 'absolute' | 'fixed' positioning strategy  
+- `options.offset` - Number pixel offset from target
+- `options.flip` - Boolean enable collision-based position flipping
+- `options.shift` - Boolean enable boundary-constrained shifting
+- `options.boundary` - Element | 'viewport' for collision detection
+
+**Returns:** Query instance for chaining
+
+### `getBounds(options)`
+Get comprehensive position/size data with coordinate system awareness.
+
+- `options.relative` - Element | 'viewport' | 'document' for coordinate system
+- `options.includeMargin` - Boolean to include margin in calculations
+
+**Returns:** Object with {x, y, width, height, top, left, right, bottom}
+
+---
+
+## Three Coordinate Systems
+
+### 1. Relative to Offset Parent (Default)
+Uses Query's enhanced `offsetParent()` that accounts for CSS transforms.
+
+```javascript
+$('.tooltip').position('.trigger', {
+  placement: 'top',
+  // Positioned relative to true offset parent (accounts for transforms)
+});
+```
+
+### 2. Relative to Specific Element  
+Position relative to any element, crossing shadow DOM boundaries when using `$$`.
+
+```javascript
+$$('.dropdown-menu').position('.dropdown-trigger', {
+  placement: 'bottom-start',
+  flip: true  // Auto-flip if no space below
+});
+```
+
+### 3. Absolute to Viewport
+Position relative to viewport top-left, accounting for scroll.
+
+```javascript
+$('.modal').position('viewport', {
+  placement: 'center',
+  strategy: 'fixed'  // Fixed positioning for overlays
+});
+```
+
+---
+
+## Collision Detection (Based on Original SUI Logic)
+
+### Systematic Position Trying
+```javascript
+// Try preferred position → check fit → try next logical position → repeat
+const positionStrategies = {
+  'opposite': ['top' → 'bottom', 'left' → 'right'],
+  'adjacent': ['top-start' → 'top-center' → 'top-end'] 
+};
+```
+
+### Boundary Collision Check
+```javascript
+// Calculate distance from viewport/boundary edges
+const distanceFromBoundary = {
+  top: offset.top - boundary.top,
+  bottom: boundary.bottom - (offset.top + popup.height),
+  left: offset.left - boundary.left,  
+  right: boundary.right - (offset.left + popup.width)
+};
+
+// Check if offstage (with jitter tolerance)
+const isOffstage = Object.values(distanceFromBoundary).some(distance => distance < -jitter);
+```
+
+### Fallback Position Chain
+```javascript
+const fallbackChain = {
+  'top-start': ['top-center', 'top-end', 'bottom-start', 'left-center', 'right-center'],
+  'bottom-start': ['bottom-center', 'bottom-end', 'top-start', 'left-center'],
+  // ... systematic fallback for all positions
+};
+```
+
+---
+
+## Essential Features
+
+### RTL Layout Support
+```javascript
+// Automatic position flipping for right-to-left layouts
+if (isRTL) {
+  placement = placement.replace(/left|right/g, match => 
+    match === 'left' ? 'right' : 'left'
+  );
+}
+```
+
+### Smart Arrow Positioning  
+```javascript
+// Adjust offset for small targets to center arrows
+if (target.width <= arrowSize * 2) {
+  offset += target.width / 2 - arrowOffset;
+}
+```
+
+### Multiple Placement Options
+- **Basic:** 'top', 'bottom', 'left', 'right'
+- **Aligned:** 'top-start', 'top-center', 'top-end'  
+- **Centered:** 'center' (for modals)
+
+---
+
+## Implementation Strategy
+
+### Phase 1: Core Positioning (2-3KB)
+- Three coordinate systems
+- Basic placement without collision detection
+- Shadow DOM coordinate translation
+
+### Phase 2: Collision Detection (2-3KB additional)  
+- Boundary checking and `isOffstage()` logic
+- Position flipping strategies ('opposite', 'adjacent')
+- Systematic fallback chain
+
+### Phase 3: Advanced Features (1KB additional)
+- RTL layout support  
+- Arrow positioning adjustments
+- Performance optimizations
+
+---
+
+## Based on Proven SUI Logic
+
+The collision detection is based on the original Semantic UI popup positioning system, which has been battle-tested across thousands of implementations. Key advantages:
+
+1. **Proven approach** - Logic from production SUI popup component
+2. **Right complexity level** - Essential collision handling without over-engineering  
+3. **Systematic fallbacks** - Predictable position trying with clear fallback chains
+4. **Boundary awareness** - Proper viewport and container boundary detection
+5. **Performance focused** - Efficient collision detection with jitter tolerance
+
+This provides the positioning capabilities that Semantic UI components actually need, without the complexity of full-featured positioning libraries.
+
+---
+
+## Usage Examples
+
+### Dropdown with Collision Detection
+```javascript
+$$('.dropdown-menu').position('.trigger', {
+  placement: 'bottom-start',
+  flip: true,        // Flip to top if no space below
+  shift: true,       // Shift horizontally to stay in bounds
+  boundary: 'viewport'
+});
+```
+
+### Tooltip with Multiple Fallbacks
+```javascript
+$('.tooltip').position('.target', {
+  placement: 'top',
+  flip: true,
+  offset: 8,
+  // Will try: top → bottom → left → right → center
+});
+```
+
+### Modal Centering
+```javascript  
+$('.modal').position('viewport', {
+  placement: 'center',
+  strategy: 'fixed',
+  boundary: 'viewport'
+});
+```
+
+This strikes the right balance between functionality and complexity, providing essential positioning with proven collision detection logic.
\ No newline at end of file
diff --git a/ai/proposals/query-positioning.md b/ai/proposals/query-positioning.md
new file mode 100644
index 000000000..8b0f78ff5
--- /dev/null
+++ b/ai/proposals/query-positioning.md
@@ -0,0 +1,159 @@
+# Query Positioning Extension
+
+> **Scope:** Modern positioning system for Shadow DOM components  
+> **Status:** High complexity, significant file size impact  
+> **Size Impact:** Large - complex positioning algorithms
+
+---
+
+## Core Positioning Method
+
+### `position(target, options)`
+Position elements relative to target with Shadow DOM and viewport awareness.
+
+- `target` - Element | Query | selector to position relative to
+- `options.placement` - String placement ('top', 'bottom', 'left', 'right', 'top-start', 'bottom-end')
+- `options.boundary` - Element | 'viewport' | 'clippingAncestors' for collision detection
+- `options.offset` - Number | {mainAxis, crossAxis} for positioning offset
+- `options.strategy` - 'absolute' | 'fixed' positioning strategy
+
+### `getBounds(options)`
+Get comprehensive position/size data.
+
+- `options.relative` - Element | 'viewport' | 'document' for coordinate system
+- `options.includeBorder` - Boolean to include border in calculations  
+- `options.includeMargin` - Boolean to include margin in calculations
+
+**Returns:** Object with {x, y, width, height, top, left, right, bottom, viewport: {...}}
+
+---
+
+## Complexity Analysis
+
+### Shadow DOM Challenges
+- **Coordinate system translation** - Converting positions across shadow boundaries
+- **Clipping context calculation** - Finding actual clipping ancestors across shadow roots
+- **Event handling** - Positioning updates on scroll/resize across shadow contexts
+
+### Positioning Algorithm Complexity
+- **Collision detection** - Viewport and boundary collision calculations
+- **Flip/shift logic** - Automatic repositioning when space is insufficient
+- **Multi-axis positioning** - Handling both main and cross axis positioning
+- **Scroll container handling** - Positioning within scrollable ancestors
+
+### File Size Impact
+**Conservative estimate:** 8-12KB gzipped for full implementation
+
+**Why so large:**
+- Comprehensive coordinate system math
+- Shadow DOM traversal algorithms  
+- Viewport intersection calculations
+- Collision detection and automatic repositioning
+- Cross-browser coordinate system handling
+
+---
+
+## Middleware vs Built-in Approach
+
+### Option 1: Built-in Algorithms
+```javascript
+$('.tooltip').position(target, {
+  placement: 'top',
+  autoFlip: true,     // Built-in flip on collision
+  autoShift: true,    // Built-in shift on collision  
+  offset: 8
+});
+```
+
+**Pros:** Simpler API, smaller total size for common cases  
+**Cons:** Less flexible, still substantial core size
+
+### Option 2: Middleware System (Floating UI style)
+```javascript
+$('.tooltip').position(target, {
+  placement: 'top',
+  middleware: [
+    offset(8),
+    flip(),
+    shift(),
+    arrow({ element: '.arrow' })
+  ]
+});
+```
+
+**Pros:** Highly flexible, tree-shakeable middleware  
+**Cons:** Larger total size, more complex API
+
+---
+
+## Baseline 2025 Optimizations
+
+### Available APIs
+- **CSS Typed OM** - More efficient style calculations
+- **Intersection Observer v2** - Better viewport detection
+- **CSS Container Queries** - Size-based positioning logic
+- **CSS Anchor Positioning** - Native browser positioning (limited support)
+
+### Potential Shortcuts
+```javascript
+// Use modern APIs for efficient calculations
+const bounds = element.getBoundingClientRect();
+const computed = element.computedStyleMap();
+const viewport = new IntersectionObserver(...);
+```
+
+---
+
+## Recommendation: Plugin Architecture
+
+Given the file size and complexity, positioning should be the flagship plugin demonstrating the plugin system:
+
+### Benefits
+1. **Optional inclusion** - Only import if needed
+2. **Tree-shakeable** - Import only required positioning features
+3. **Iterative development** - Easier to refine complex APIs
+4. **Baseline 2025 focus** - Can use cutting-edge APIs without core compatibility concerns
+
+### Plugin Structure
+```javascript
+// Core import
+import { $ } from '@semantic-ui/query';
+
+// Positioning plugin with tree-shakeable middleware
+import { positioning, flip, shift, offset } from '@semantic-ui/query/plugins/positioning';
+
+$.use(positioning);
+
+// Usage
+$('.dropdown-menu').position('.dropdown-trigger', {
+  placement: 'bottom-start',
+  middleware: [offset(4), flip(), shift()]
+});
+```
+
+### Size Comparison
+- **Core Query:** ~3KB gzipped  
+- **+ Positioning Plugin:** +8-12KB gzipped
+- **Total when needed:** ~11-15KB gzipped
+- **Total when not needed:** ~3KB gzipped
+
+---
+
+## Implementation Phases
+
+### Phase 1: Basic positioning
+- Simple placement without collision detection
+- Shadow DOM coordinate translation
+- Viewport-relative positioning
+
+### Phase 2: Collision handling  
+- Flip and shift algorithms
+- Boundary detection
+- Automatic repositioning
+
+### Phase 3: Advanced features
+- Middleware system
+- Animation integration
+- Performance optimizations
+
+This keeps the core lean while providing powerful positioning for complex component scenarios.
\ No newline at end of file
diff --git a/ai/proposals/transition-outline.js b/ai/proposals/transition-outline.js
new file mode 100644
index 000000000..249ae5977
--- /dev/null
+++ b/ai/proposals/transition-outline.js
@@ -0,0 +1,280 @@
+const module = {
+
+  // --- Getters: Methods for retrieving information, settings, or state. ---
+  get: {
+    // Retrieves a specific setting value (e.g., 'animation', 'duration', 'onComplete').
+    setting(name) {
+
+    },
+
+    // Parses and returns the core animation name from the settings.
+    animationName() {
+
+    },
+
+    // Determines and returns the animation direction ('in' or 'out') based on the element's current visibility.
+    direction() {
+
+    },
+
+    // Returns the element's root node (either the `document` or its parent `ShadowRoot`).
+    elementRoot() {
+
+    },
+
+    // Orchestrates the display type detection, using the cache first before determining it.
+    displayType() {
+
+    },
+
+    // Retrieves the display type from the internal cache.
+    cachedDisplayType() {
+
+    },
+
+    // Returns the promise associated with the current animation.
+    promise() {
+
+    },
+
+    // Retrieves the next animation's settings object from the queue.
+    nextInQueue() {
+
+    },
+
+    // Calculates the stagger delay for an element in a group animation.
+    intervalDelayFor(index) {
+
+    },
+
+    // Returns the underlying DOM elements from the current `Query` context.
+    elements() {
+
+    },
+  },
+
+  // --- Setters: Methods for applying a state, class, or property. ---
+  set: {
+    // Flags the module as currently processing an animation (for queuing purposes).
+    busy() {
+
+    },
+
+    // Sets the `display` style property on the element.
+    display(type) {
+
+    },
+
+    // Adds the specific animation classes (e.g., `.fade`, `.up`, `.in`).
+    animationClasses(name, direction) {
+
+    },
+
+    // Adds the `.animating` class.
+    animating() {
+
+    },
+
+    // Adds the final `.visible` class upon completion of an "in" animation.
+    visible() {
+
+    },
+
+    // Adds the final `.hidden` class upon completion of an "out" animation.
+    hidden() {
+
+    },
+
+    // Adds the `.looping` class to enable continuous animation.
+    looping() {
+
+    },
+  },
+
+  // --- Removers: Methods for undoing a state, class, or property. ---
+  remove: {
+    // Clears the "busy" flag after an animation (and its queue) completes.
+    busy() {
+
+    },
+
+    // Removes `.visible` and `.hidden` classes at the start of a new animation.
+    stateClasses() {
+
+    },
+
+
+
+    // Removes the specific animation classes (e.g., `.fade`, `.up`, `.in`) after completion.
+    animationClasses() {
+
+    },
+
+    // Removes the `.animating` class.
+    animating() {
+
+    },
+
+    // Removes the `.looping` class to stop a continuous animation.
+    looping() {
+
+    },
+  },
+
+  // --- State Checks: Methods that return a boolean about the module or element's current state. ---
+  is: {
+    // Checks if animations are globally disabled for the module.
+    disabled() {
+
+    },
+
+    // Checks if the `.animating` class is present.
+    animating() {
+
+    },
+
+    // Checks the internal "busy" flag to determine if an animation or queue is active.
+    busy() {
+
+    },
+
+    // Returns `true` if the calculated direction is 'in'.
+    inward(direction) {
+
+    },
+
+    // Returns `true` if the calculated direction is 'out'.
+    outward(direction) {
+
+    },
+  },
+
+  // --- Existence Checks: Methods that return a boolean about the existence of something. ---
+  has: {
+    // Checks if the CSSOM rules for a given animation have already been injected.
+    stylesheetRulesFor(animation) {
+
+    },
+
+    // Checks if a given root has already adopted the master stylesheet.
+    adoptedStylesheet(root) {
+
+    },
+
+    // Checks if there are any animations waiting in the queue for the element.
+    queue() {
+
+    },
+  },
+
+  // --- CSS Engine: Methods for setting up and managing the CSS engine. ---
+  create: {
+    // (Initialization) Creates the master `CSSStyleSheet` object in memory.
+    stylesheet() {
+
+    },
+  },
+  inject: {
+    // Injects the `@keyframes` and class rules for a specific animation into the master stylesheet.
+    stylesheetRulesFor(animation) {
+
+    },
+  },
+  adopt: {
+    // Adds the master stylesheet to a given root's (`document` or `ShadowRoot`) `adoptedStyleSheets` array.
+    stylesheet(root) {
+
+    },
+  },
+
+  // --- Queue Management: Methods for controlling the animation queue. ---
+  add: {
+    // Pushes a new animation's settings object to the element's queue.
+    toQueue() {
+
+    },
+  },
+  run: {
+    // Dequeues and executes the next animation.
+    nextInQueue() {
+
+    },
+  },
+
+  // --- Execution & Logic: Core logic and utility methods. ---
+  determine: {
+    // The subroutine that encapsulates the element-cloning logic to find the natural `display` style.
+    displayType() {
+
+    },
+  },
+  listen: {
+    // Attaches the `animationend` event listener to the element.
+    forCompletion() {
+
+    },
+  },
+  resolve: {
+    // Fulfills the promise associated with the completed animation.
+    promise() {
+
+    },
+  },
+  schedule: {
+    // A conceptual wrapper for `setTimeout` used to stagger animations in a group.
+    animation(delay) {
+
+    },
+  },
+  reverse: {
+    // Reverses the order of a `Query` collection.
+    elements($elements) {
+
+    },
+  },
+
+  // --- Public Control Methods: User-callable methods to interrupt animations. ---
+  stop() {
+    // Finishes the current animation immediately and jumps to its end state.
+  },
+  stopAll() {
+    // Finishes the current animation immediately and clears any pending animations in the queue.
+  },
+  clear: {
+    // Removes any pending animations from the queue without affecting the current animation.
+    queue() {
+
+    },
+  },
+
+  // --- Event Triggers: Methods for firing user-provided lifecycle callbacks. ---
+  trigger: {
+    // Fires the `onStart` callback.
+    onStart() {
+
+    },
+
+    // Fires the `onComplete` callback.
+    onComplete() {
+
+    },
+
+    // Fires the `onShow` callback.
+    onShow() {
+
+    },
+
+    // Fires the `onHide` callback.
+    onHide() {
+
+    },
+  },
+
+  // --- Debug: Methods for internal logging. ---
+  debug: {
+    // Outputs a debug message to the console if debugging is enabled.
+    log(message) {
+
+    },
+  },
+};
diff --git a/ai/workflows/add-query-method.mdx b/ai/workflows/add-query-method.mdx
new file mode 100644
index 000000000..99cef45f3
--- /dev/null
+++ b/ai/workflows/add-query-method.mdx
@@ -0,0 +1,310 @@
+# Adding a New Query Method
+
+This workflow outlines the complete process for implementing a new method on the Query class, based on lessons learned from adding the `data()` method.
+
+## Overview
+
+Adding a new Query method involves 5 main steps:
+1. **Implementation** - Add the method to the Query class
+2. **Testing** - Write comprehensive tests
+3. **Types** - Update TypeScript definitions
+4. **Documentation** - Add API documentation
+5. **Release Notes** - Update change log (if not already done)
+
+## File Locations
+
+```
+packages/query/src/query.js             # Main implementation
+packages/query/test/dom/query.test.js    # DOM-based unit tests
+packages/query/test/browser/query.test.js # Browser-only tests (window, custom elements, etc.)
+packages/query/types/query.d.ts         # TypeScript definitions
+docs/src/pages/api/query/*.mdx          # API documentation
+RELEASE-NOTES.md                        # Change log
+```
+
+## Step 1: Implementation
+
+### Location
+Add your method to `/packages/query/src/query.js`
+
+### Key Conventions
+
+#### Use Semantic UI Utils
+Query uses utilities from `@semantic-ui/utils`. Use existing imported helpers from the import statement at the top of `query.js`, or import additional ones as needed. See the comprehensive [Utils Package Guide](../packages/utils.md) for all available utilities.
+
+#### Method Placement
+- Add new methods before the comment `// special helper for SUI components`
+- Keep related methods grouped together
+
+#### Return Value Patterns
+Query follows consistent patterns for single vs multiple elements:
+
+**Getters:**
+```javascript
+// Single element: return the value directly
+// Multiple elements: return array of values
+const values = this.map(el => /* get value */);
+return this.length === 1 ? values[0] : values;
+```
+
+**Setters:**
+```javascript
+// Always return Query instance for chaining
+return this.each(el => {
+  // set value on each element
+});
+```
+
+#### Use Existing Query Methods
+- Use `this.el()` instead of `this[0]` for first element
+- Use `this.each()` for iteration over elements  
+- Use `this.map()` for transforming elements to values
+- Use semantic-ui utils for safe operations (see imports at top of file)
+
+#### Error Handling
+```javascript
+// Check for empty selections
+if (this.length === 0) {
+  return undefined;
+}
+```
+
+### Example Structure
+```javascript
+methodName(param1, param2) {
+  if (param2 !== undefined) {
+    // Setter - return Query for chaining
+    return this.each(el => {
+      // modify each element
+    });
+  }
+  
+  if (param1 !== undefined) {
+    // Getter with parameter
+    if (this.length === 0) {
+      return undefined;
+    }
+    const values = this.map(el => /* get value from element */);
+    return this.length === 1 ? values[0] : values;
+  }
+  
+  // Getter without parameters
+  if (this.length === 0) {
+    return undefined;
+  }
+  const allValues = this.map(el => {
+    // collect all relevant data
+  });
+  return this.length === 1 ? allValues[0] : allValues;
+}
+```
+
+## Step 2: Testing
+
+### Location
+Add tests to `/packages/query/test/dom/query.test.js` for standard DOM operations.
+
+For features requiring full browser support (window object, custom elements, shadow DOM, etc.) that cannot run as unit tests, add tests to `/packages/query/test/browser/query.test.js` instead.
+
+### Test Structure
+```javascript
+describe('methodName', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('should handle the basic functionality', () => {
+    // test implementation
+  });
+
+  // ... more tests
+});
+```
+
+### Essential Test Cases
+1. **Basic getter/setter functionality**
+2. **Single element behavior**
+3. **Multiple element behavior** 
+4. **Empty selection handling**
+5. **Edge cases** (missing properties, null values, etc.)
+6. **Chaining** (setters return Query instance)
+7. **Type consistency** (what gets returned vs what gets set)
+
+### Test Patterns
+```javascript
+// Setting values
+$('div').methodName('key', 'value');
+expect(/* verify DOM change */).toBe('value');
+
+// Getting from single element  
+const result = $('div').methodName('key');
+expect(result).toBe('expectedValue');
+
+// Getting from multiple elements
+const results = $('div').methodName('key'); 
+expect(results).toEqual(['value1', 'value2']);
+
+// Chaining
+const $result = $('div').methodName('key', 'value');
+expect($result).toBeInstanceOf(Query);
+expect($result[0]).toBe(/* original element */);
+```
+
+## Step 3: TypeScript Definitions
+
+### Location
+Add type definitions to `/packages/query/types/query.d.ts`
+
+### Method Overloads
+Use method overloads to properly type different usage patterns:
+
+```typescript
+/**
+ * Sets a value (when both parameters provided)
+ */
+methodName(param1: string, param2: string): this;
+/**
+ * Gets a specific value (when one parameter provided)
+ */
+methodName(param1: string): string | string[] | undefined;
+/**
+ * Gets all values (when no parameters provided)
+ */
+methodName(): SomeType | SomeType[] | undefined;
+```
+
+### JSDoc Comments
+Include proper JSDoc with:
+- Description of what the method does
+- `@see` link to documentation (use pattern: `https://next.semantic-ui.com/api/query/category#methodname`)
+- Parameter descriptions
+- Return value descriptions
+
+### Type Patterns
+- Use `PlainObject<T>` for object types
+- Use `string | string[] | undefined` for getter return types
+- Use `this` for setter return types (enables chaining)
+
+## Step 4: Documentation
+
+### Location
+Add documentation to the appropriate file in `/docs/src/pages/api/query/`
+
+Choose the most relevant category:
+- `attributes.mdx` - for attribute-related methods
+- `content.mdx` - for content manipulation
+- `css.mdx` - for styling methods
+- `events.mdx` - for event handling
+- etc.
+
+### Documentation Structure
+```markdown
+## methodName
+
+Brief description of what the method does.
+
+### Syntax
+
+#### Get All Values
+```javascript
+$('selector').methodName()
+```
+
+#### Get Specific Value  
+```javascript
+$('selector').methodName(key)
+```
+
+#### Set Value
+```javascript
+$('selector').methodName(key, value)
+```
+
+### Parameters
+| Name  | Type   | Description                    |
+|-------|--------|--------------------------------|
+| key   | string | Description of key parameter   |
+| value | string | Description of value parameter |
+
+### Returns
+
+#### Get All Values
+- **Single Element** Description of single element return
+- **Multiple Elements** Description of multiple element return
+
+#### Get Specific Value
+- **Single Element** Description of single element return  
+- **Multiple Elements** Description of multiple element return
+
+#### Set Value
+[Query object](/query/basic#the-query-object) (for chaining).
+
+### Usage
+
+#### Basic Examples
+```javascript
+// Example usage with explanatory comments
+```
+
+#### Working with Multiple Elements
+```javascript
+// Show single vs multiple element behavior
+```
+
+### Notes
+- Important behavioral notes
+- Edge cases to be aware of
+- Related methods or concepts
+```
+
+## Step 5: Release Notes
+
+### Location
+`RELEASE-NOTES.md` (may already be updated)
+
+### Format
+Add entry following the existing pattern:
+```markdown
+# Version X.X.X
+
+* **Query** - Added `methodName()` for [brief description of purpose]
+```
+
+## Key Learnings & Best Practices
+
+### Code Style
+1. **Use existing utils** - Don't reinvent iteration, object access, etc.
+2. **Follow return patterns** - Single element returns value, multiple returns array
+3. **Handle empty selections** - Always check `this.length === 0`
+4. **Use semantic methods** - `this.el()`, `this.each()`, `this.map()`
+
+### Testing
+1. **Test all usage patterns** - getter without args, getter with args, setter
+2. **Test edge cases** - empty selections, missing properties, null values
+3. **Test both single and multiple elements** - behavior should be consistent
+4. **Verify chaining works** - setters return Query instance
+
+### Documentation
+1. **Include practical examples** - show real-world usage
+2. **Document return value differences** - single vs multiple elements
+3. **Use existing patterns** - follow format of other method docs
+4. **Add helpful notes** - edge cases, related concepts
+
+### Common Pitfalls
+1. **Don't use `this[0]`** - use `this.el()` 
+2. **Don't use native iteration** - use `each()` utility
+3. **Don't forget type overloads** - needed for proper TypeScript support
+4. **Don't skip empty selection checks** - prevents runtime errors
+5. **Remember array vs single returns** - follow established patterns
+
+## Verification Checklist
+
+- [ ] Method implemented in `query.js` using semantic-ui utils
+- [ ] Comprehensive tests added covering all usage patterns
+- [ ] TypeScript definitions added with proper overloads
+- [ ] Documentation added to appropriate category file
+- [ ] Release notes updated (if needed)
+- [ ] Tests pass (`npm test` in packages/query)
+- [ ] Method follows single/multiple element return patterns
+- [ ] Setter returns Query instance for chaining
+- [ ] Empty selection handling implemented
\ No newline at end of file
diff --git a/ai/workspace/.esbuild/index.js b/ai/workspace/.esbuild/index.js
new file mode 100644
index 000000000..ce7f4bc32
--- /dev/null
+++ b/ai/workspace/.esbuild/index.js
@@ -0,0 +1,114 @@
+var index_default = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AI Workspace - Semantic UI Component Testing</title>
+    <link rel="stylesheet" href="/dist/semantic-ui.css">
+    <style>
+        body {
+            font-family: system-ui, -apple-system, sans-serif;
+            margin: 0;
+            padding: 2rem;
+            background: #f8f9fa;
+        }
+        .container {
+            max-width: 800px;
+            margin: 0 auto;
+            background: white;
+            padding: 2rem;
+            border-radius: 8px;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+        }
+        .component-list {
+            margin-top: 2rem;
+        }
+        .component-link {
+            display: block;
+            padding: 1rem;
+            margin: 0.5rem 0;
+            background: #f1f3f4;
+            text-decoration: none;
+            color: #333;
+            border-radius: 4px;
+            transition: background 0.2s;
+        }
+        .component-link:hover {
+            background: #e8eaed;
+        }
+        .code {
+            background: #f1f3f4;
+            padding: 0.25rem 0.5rem;
+            border-radius: 3px;
+            font-family: 'Courier New', monospace;
+            font-size: 0.9em;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>\u{1F916} AI Workspace</h1>
+        <p>Simple testing environment for Semantic UI components.</p>
+        
+        <h2>Getting Started</h2>
+        <ol>
+            <li>Create component files in <span class="code">ai/workspace/components/my-component/</span></li>
+            <li>Use the standard pattern: <span class="code">component.js</span>, <span class="code">component.html</span>, <span class="code">component.css</span></li>
+            <li>Test your component at <span class="code">/component.html?name=my-component</span></li>
+        </ol>
+
+        <h2>Quick Links</h2>
+        <div class="component-list">
+            <a href="/component.html" class="component-link">
+                \u{1F4DD} Component Tester - Test any component
+            </a>
+            <a href="/component.html?name=example" class="component-link">
+                \u{1F3AF} Example Component - See how it works
+            </a>
+        </div>
+
+        <h2>Available Components</h2>
+        <div id="components-list">
+            <p>Loading components...</p>
+        </div>
+    </div>
+
+    <script type="module">
+        // Scan for available components
+        async function loadComponentsList() {
+            try {
+                const response = await fetch('/components/');
+                const html = await response.text();
+                
+                // Simple parsing of directory listing
+                const parser = new DOMParser();
+                const doc = parser.parseFromString(html, 'text/html');
+                const links = doc.querySelectorAll('a[href]');
+                
+                const components = Array.from(links)
+                    .map(link => link.getAttribute('href'))
+                    .filter(href => href && href !== '../' && href.endsWith('/'))
+                    .map(href => href.replace('/', ''));
+
+                const container = document.getElementById('components-list');
+                if (components.length > 0) {
+                    container.innerHTML = components.map(name => 
+                        \`<a href="/component.html?name=\${name}" class="component-link">
+                            \u{1F9E9} \${name}
+                        </a>\`
+                    ).join('');
+                } else {
+                    container.innerHTML = '<p>No components found. Create your first component!</p>';
+                }
+            } catch (error) {
+                document.getElementById('components-list').innerHTML = 
+                    '<p>Could not load components list.</p>';
+            }
+        }
+
+        loadComponentsList();
+    <\/script>
+</body>
+</html>`;
+export { index_default as default };
+// # sourceMappingURL=index.js.map
diff --git a/ai/workspace/.esbuild/index.js.map b/ai/workspace/.esbuild/index.js.map
new file mode 100644
index 000000000..38393fed8
--- /dev/null
+++ b/ai/workspace/.esbuild/index.js.map
@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../public/index.html"],
+  "sourcesContent": ["<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n    <title>AI Workspace - Semantic UI Component Testing</title>\n    <link rel=\"stylesheet\" href=\"/dist/semantic-ui.css\">\n    <style>\n        body {\n            font-family: system-ui, -apple-system, sans-serif;\n            margin: 0;\n            padding: 2rem;\n            background: #f8f9fa;\n        }\n        .container {\n            max-width: 800px;\n            margin: 0 auto;\n            background: white;\n            padding: 2rem;\n            border-radius: 8px;\n            box-shadow: 0 2px 10px rgba(0,0,0,0.1);\n        }\n        .component-list {\n            margin-top: 2rem;\n        }\n        .component-link {\n            display: block;\n            padding: 1rem;\n            margin: 0.5rem 0;\n            background: #f1f3f4;\n            text-decoration: none;\n            color: #333;\n            border-radius: 4px;\n            transition: background 0.2s;\n        }\n        .component-link:hover {\n            background: #e8eaed;\n        }\n        .code {\n            background: #f1f3f4;\n            padding: 0.25rem 0.5rem;\n            border-radius: 3px;\n            font-family: 'Courier New', monospace;\n            font-size: 0.9em;\n        }\n    </style>\n</head>\n<body>\n    <div class=\"container\">\n        <h1>\uD83E\uDD16 AI Workspace</h1>\n        <p>Simple testing environment for Semantic UI components.</p>\n        \n        <h2>Getting Started</h2>\n        <ol>\n            <li>Create component files in <span class=\"code\">ai/workspace/components/my-component/</span></li>\n            <li>Use the standard pattern: <span class=\"code\">component.js</span>, <span class=\"code\">component.html</span>, <span class=\"code\">component.css</span></li>\n            <li>Test your component at <span class=\"code\">/component.html?name=my-component</span></li>\n        </ol>\n\n        <h2>Quick Links</h2>\n        <div class=\"component-list\">\n            <a href=\"/component.html\" class=\"component-link\">\n                \uD83D\uDCDD Component Tester - Test any component\n            </a>\n            <a href=\"/component.html?name=example\" class=\"component-link\">\n                \uD83C\uDFAF Example Component - See how it works\n            </a>\n        </div>\n\n        <h2>Available Components</h2>\n        <div id=\"components-list\">\n            <p>Loading components...</p>\n        </div>\n    </div>\n\n    <script type=\"module\">\n        // Scan for available components\n        async function loadComponentsList() {\n            try {\n                const response = await fetch('/components/');\n                const html = await response.text();\n                \n                // Simple parsing of directory listing\n                const parser = new DOMParser();\n                const doc = parser.parseFromString(html, 'text/html');\n                const links = doc.querySelectorAll('a[href]');\n                \n                const components = Array.from(links)\n                    .map(link => link.getAttribute('href'))\n                    .filter(href => href && href !== '../' && href.endsWith('/'))\n                    .map(href => href.replace('/', ''));\n\n                const container = document.getElementById('components-list');\n                if (components.length > 0) {\n                    container.innerHTML = components.map(name => \n                        `<a href=\"/component.html?name=${name}\" class=\"component-link\">\n                            \uD83E\uDDE9 ${name}\n                        </a>`\n                    ).join('');\n                } else {\n                    container.innerHTML = '<p>No components found. Create your first component!</p>';\n                }\n            } catch (error) {\n                document.getElementById('components-list').innerHTML = \n                    '<p>Could not load components list.</p>';\n            }\n        }\n\n        loadComponentsList();\n    </script>\n</body>\n</html>"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;",
+  "names": []
+}
diff --git a/ai/workspace/README.md b/ai/workspace/README.md
new file mode 100644
index 000000000..e08aabf7b
--- /dev/null
+++ b/ai/workspace/README.md
@@ -0,0 +1,384 @@
+# AI Workspace - MCP Debugging Environment
+
+Complete web component debugging environment with Model Context Protocol (MCP) tools for AI agents.
+
+## 🎯 Features
+
+- **MCP WebSocket Server** - Real-time communication between AI agents and browser
+- **Shadow DOM-Aware Debugging** - Pierces web component boundaries 
+- **Component Auto-Discovery** - Automatic registration and tracking
+- **Real-Time Event Streaming** - Monitor component events as they happen
+- **Code Execution in Context** - Run JavaScript in component scope
+- **State Introspection** - Deep component state analysis
+- **Mutation Tracking** - Track DOM changes over time
+- **CSS Analysis** - Computed styles and custom properties inspection
+
+## 🚀 Quick Start
+
+### Start the Development Environment
+
+```bash
+npm run dev:workspace
+```
+
+This starts:
+- **Web Server**: `http://localhost:8080`
+- **MCP WebSocket**: `ws://localhost:8081`
+
+### Access the Interface
+
+- **Main Dashboard**: `http://localhost:8080/public/`
+- **Component Tester**: `http://localhost:8080/public/component.html`
+- **Test Component Demo**: `http://localhost:8080/public/component.html?name=test-component`
+
+## 🛠️ MCP Tools for AI Agents
+
+### Core Inspection Tools
+
+#### `inspect_component`
+Deep analysis of component structure, attributes, and shadow DOM.
+
+```javascript
+{
+  "tool": "inspect_component",
+  "params": {
+    "selector": "#my-component",
+    "depth": 3
+  }
+}
+```
+
+#### `execute_in_component`
+Execute JavaScript code within component context.
+
+```javascript
+{
+  "tool": "execute_in_component", 
+  "params": {
+    "selector": "test-component",
+    "code": "return { counter: host.counter, state: host.state }"
+  }
+}
+```
+
+#### `monitor_events`
+Real-time event monitoring with WebSocket streaming.
+
+```javascript
+{
+  "tool": "monitor_events",
+  "params": {
+    "selector": "#demo-test",
+    "events": ["click", "counter-changed", "section-toggled"]
+  }
+}
+```
+
+### Shadow DOM Tools
+
+#### `query_shadow_dom`
+Query elements within shadow DOM boundaries.
+
+```javascript
+{
+  "tool": "query_shadow_dom",
+  "params": {
+    "selector": "test-component",
+    "query": "button.increment-btn"
+  }
+}
+```
+
+#### `get_computed_styles`
+Analyze CSS styles and custom properties.
+
+```javascript
+{
+  "tool": "get_computed_styles",
+  "params": {
+    "selector": "test-component",
+    "elementPath": ".counter-display"
+  }
+}
+```
+
+### State & History Tools
+
+#### `get_component_state`
+Retrieve component's internal state and methods.
+
+```javascript
+{
+  "tool": "get_component_state",
+  "params": {
+    "selector": "#demo-test"
+  }
+}
+```
+
+#### `mutation_history`
+Track recent DOM changes within components.
+
+```javascript
+{
+  "tool": "mutation_history",
+  "params": {
+    "selector": "test-component",
+    "count": 10
+  }
+}
+```
+
+#### `list_components`
+Discover all web components on the page.
+
+```javascript
+{
+  "tool": "list_components",
+  "params": {}
+}
+```
+
+## 🧩 Creating Components
+
+### Standard Component Structure
+
+```
+ai/workspace/components/my-component/
+├── component.js        # Main component definition
+├── component.html      # Template (optional)
+└── component.css       # Styles (optional)
+```
+
+### Example Component
+
+```javascript
+// component.js
+class MyComponent extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this._counter = 0;
+  }
+  
+  connectedCallback() {
+    this.render();
+  }
+  
+  render() {
+    this.shadowRoot.innerHTML = `
+      <style>
+        :host { display: block; padding: 1rem; }
+        button { padding: 0.5rem 1rem; }
+      </style>
+      <div>
+        <p>Counter: ${this._counter}</p>
+        <button onclick="this.getRootNode().host.increment()">+</button>
+      </div>
+    `;
+  }
+  
+  increment() {
+    this._counter++;
+    this.render();
+    this.dispatchEvent(new CustomEvent('counter-changed', {
+      detail: { value: this._counter },
+      bubbles: true,
+      composed: true
+    }));
+  }
+  
+  get counter() { return this._counter; }
+}
+
+customElements.define('my-component', MyComponent);
+```
+
+## 🔍 Debugging Workflow
+
+### 1. Component Discovery
+```javascript
+// Find all components
+await tools.list_components({});
+
+// Inspect specific component  
+await tools.inspect_component({
+  selector: "my-component",
+  depth: 2
+});
+```
+
+### 2. Event Monitoring
+```javascript
+// Monitor user interactions
+await tools.monitor_events({
+  selector: "my-component", 
+  events: ["click", "counter-changed"]
+});
+
+// Events stream to WebSocket automatically
+```
+
+### 3. State Analysis
+```javascript
+// Check component state
+await tools.get_component_state({
+  selector: "my-component"
+});
+
+// Execute custom code
+await tools.execute_in_component({
+  selector: "my-component",
+  code: "return { counter: host.counter, methods: Object.getOwnPropertyNames(host.__proto__) }"
+});
+```
+
+### 4. Style Debugging
+```javascript
+// Analyze computed styles
+await tools.get_computed_styles({
+  selector: "my-component",
+  elementPath: "button"
+});
+```
+
+### 5. Change Tracking
+```javascript
+// View recent mutations
+await tools.mutation_history({
+  selector: "my-component",
+  count: 5
+});
+```
+
+## 📡 WebSocket Communication
+
+### Message Types
+
+#### Tool Requests (Agent → Browser)
+```javascript
+{
+  "type": "mcp-tool-request",
+  "tool": "inspect_component",
+  "params": { "selector": "my-component" },
+  "id": "req-123"
+}
+```
+
+#### Tool Responses (Browser → Agent)
+```javascript
+{
+  "type": "mcp-tool-response", 
+  "id": "req-123",
+  "result": { /* tool output */ }
+}
+```
+
+#### Event Streams (Browser → Agent)
+```javascript
+{
+  "type": "event-triggered",
+  "selector": "my-component",
+  "event": "counter-changed",
+  "detail": {
+    "type": "counter-changed",
+    "target": "MY-COMPONENT",
+    "detail": { "value": 5 },
+    "timestamp": 1640995200000
+  }
+}
+```
+
+## 🎯 Test Components
+
+### Basic Test Component
+- **Location**: `components/test-component/component.js`
+- **Features**: Counter, themes, state management, events
+- **Usage**: Perfect for learning MCP debugging
+
+### Example Component
+- **Location**: `components/example/component.js` 
+- **Features**: Semantic UI integration, reactive templates
+- **Usage**: Framework-specific patterns
+
+## 🔧 Technical Architecture
+
+### Debug Bridge (`debug-bridge.js`)
+- Component auto-registration
+- Shadow DOM traversal
+- Event delegation and capture
+- MCP tool request handling
+- WebSocket communication
+
+### MCP Server (`build-ai-workspace.js`)
+- WebSocket server on port 8081
+- Tool request routing
+- Event broadcasting
+- Connection management
+
+### esbuild Integration
+- Debug bridge injection
+- Live reloading
+- Module serving
+- Development server
+
+## 📚 Documentation References
+
+- **MCP Tools Schema**: `/mcp-tools.js`
+- **Component Guide**: `/ai/guides/component-generation-instructions.md`
+- **Query System**: `/ai/specialized/query-system-guide.md`
+- **Mental Model**: `/ai/foundations/mental-model.md`
+
+## 🎮 Usage Examples
+
+### Debug a Broken Component
+```javascript
+// 1. Find the component
+const components = await tools.list_components({});
+
+// 2. Inspect its structure
+const structure = await tools.inspect_component({
+  selector: "broken-component"
+});
+
+// 3. Monitor for errors
+await tools.monitor_events({
+  selector: "broken-component",
+  events: ["error", "click", "change"]
+});
+
+// 4. Execute diagnostic code
+const diagnostics = await tools.execute_in_component({
+  selector: "broken-component", 
+  code: `
+    return {
+      hasErrors: !!shadow.querySelector('.error'),
+      eventListeners: getEventListeners ? getEventListeners(host) : 'Not available',
+      attributes: [...host.attributes].map(a => ({name: a.name, value: a.value}))
+    }
+  `
+});
+```
+
+### Performance Analysis
+```javascript
+// Monitor mutations for performance issues
+const mutations = await tools.mutation_history({
+  selector: "heavy-component",
+  count: 20
+});
+
+// Check computed styles for layout issues  
+const styles = await tools.get_computed_styles({
+  selector: "heavy-component",
+  elementPath: ".performance-critical-element"
+});
+```
+
+---
+
+## 🎉 Ready to Debug!
+
+The MCP debugging environment provides comprehensive tools for AI agents to inspect, monitor, and debug web components with full shadow DOM support and real-time event streaming.
+
+Start the server with `npm run dev:workspace` and begin debugging!
\ No newline at end of file
diff --git a/ai/workspace/components/example/component.css b/ai/workspace/components/example/component.css
new file mode 100644
index 000000000..4418ce34f
--- /dev/null
+++ b/ai/workspace/components/example/component.css
@@ -0,0 +1,182 @@
+:host {
+  --component-bg: var(--background-color, #ffffff);
+  --component-border: var(--border-color, #e1e5e9);
+  --component-text: var(--text-color, #333333);
+  --primary-color: var(--primary, #007bff);
+  --secondary-color: var(--secondary, #6c757d);
+  --success-color: var(--success, #28a745);
+  --spacing: var(--spacing-md, 1rem);
+  --border-radius: var(--radius, 6px);
+  
+  display: block;
+  font-family: system-ui, -apple-system, sans-serif;
+}
+
+.example-component {
+  background: var(--component-bg);
+  border: 1px solid var(--component-border);
+  border-radius: var(--border-radius);
+  padding: var(--spacing);
+  color: var(--component-text);
+  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+}
+
+.header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: var(--spacing);
+  padding-bottom: calc(var(--spacing) * 0.5);
+  border-bottom: 1px solid var(--component-border);
+}
+
+.header h3 {
+  margin: 0;
+  color: var(--component-text);
+}
+
+.content {
+  margin-bottom: var(--spacing);
+}
+
+.counter {
+  text-align: center;
+  padding: var(--spacing);
+  background: #f8f9fa;
+  border-radius: var(--border-radius);
+  margin-bottom: var(--spacing);
+}
+
+.counter p {
+  margin: 0 0 var(--spacing) 0;
+  font-size: 1.1rem;
+}
+
+.increment-btn, .toggle-btn {
+  background: var(--primary-color);
+  color: white;
+  border: none;
+  padding: 0.75rem 1.5rem;
+  border-radius: var(--border-radius);
+  cursor: pointer;
+  font-size: 1rem;
+  transition: all 0.2s ease;
+}
+
+.increment-btn:hover, .toggle-btn:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 4px 8px rgba(0,0,0,0.2);
+}
+
+.increment-btn:active, .toggle-btn:active {
+  transform: translateY(0);
+}
+
+.increment-btn:disabled, .toggle-btn:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+  transform: none !important;
+}
+
+/* Theme variations */
+.example-component.primary .increment-btn {
+  background: var(--primary-color);
+}
+
+.example-component.secondary .increment-btn {
+  background: var(--secondary-color);
+}
+
+.example-component.success .increment-btn {
+  background: var(--success-color);
+}
+
+.expanded-content {
+  background: #f1f3f4;
+  padding: var(--spacing);
+  border-radius: var(--border-radius);
+  margin-top: var(--spacing);
+  animation: slideDown 0.3s ease-out;
+}
+
+@keyframes slideDown {
+  from {
+    opacity: 0;
+    transform: translateY(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.message-section {
+  margin-bottom: var(--spacing);
+}
+
+.message-section label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 600;
+}
+
+.message-input {
+  width: 100%;
+  padding: 0.75rem;
+  border: 1px solid var(--component-border);
+  border-radius: var(--border-radius);
+  font-size: 1rem;
+  box-sizing: border-box;
+}
+
+.message-input:focus {
+  outline: none;
+  border-color: var(--primary-color);
+  box-shadow: 0 0 0 2px rgba(0,123,255,0.25);
+}
+
+.message-display {
+  margin-top: 0.5rem;
+  font-size: 0.9rem;
+  color: var(--secondary-color);
+}
+
+.debug-info {
+  background: white;
+  padding: var(--spacing);
+  border-radius: var(--border-radius);
+  border: 1px solid var(--component-border);
+}
+
+.debug-info h4 {
+  margin: 0 0 0.75rem 0;
+  color: var(--component-text);
+}
+
+.debug-info ul {
+  margin: 0;
+  padding-left: 1.5rem;
+}
+
+.debug-info li {
+  margin-bottom: 0.25rem;
+}
+
+.debug-info code {
+  background: #e9ecef;
+  padding: 0.125rem 0.375rem;
+  border-radius: 3px;
+  font-family: 'Courier New', monospace;
+  font-size: 0.9rem;
+}
+
+.footer {
+  text-align: center;
+  padding-top: calc(var(--spacing) * 0.5);
+  border-top: 1px solid var(--component-border);
+  color: var(--secondary-color);
+}
+
+.footer small {
+  font-size: 0.8rem;
+}
\ No newline at end of file
diff --git a/ai/workspace/components/example/component.html b/ai/workspace/components/example/component.html
new file mode 100644
index 000000000..353806e65
--- /dev/null
+++ b/ai/workspace/components/example/component.html
@@ -0,0 +1,52 @@
+<div class="example-component {theme}">
+  <div class="header">
+    <h3>{title}</h3>
+    <div class="controls">
+      <button class="toggle-btn" disabled="{disabled}">
+        {#if isExpanded}
+          Collapse ▲
+        {else}
+          Expand ▼
+        {/if}
+      </button>
+    </div>
+  </div>
+  
+  <div class="content">
+    <div class="counter">
+      <p>Button clicked: <strong>{clicks}</strong> times</p>
+      <button class="increment-btn {theme}" disabled="{disabled}">
+        Click me! (+1)
+      </button>
+    </div>
+    
+    {#if isExpanded}
+      <div class="expanded-content">
+        <div class="message-section">
+          <label for="message">Message:</label>
+          <input 
+            type="text" 
+            class="message-input" 
+            value="{message}"
+            disabled="{disabled}"
+            placeholder="Enter a message...">
+          <p class="message-display">Current: <em>{message}</em></p>
+        </div>
+        
+        <div class="debug-info">
+          <h4>Debug Information:</h4>
+          <ul>
+            <li>Theme: <code>{theme}</code></li>
+            <li>Disabled: <code>{disabled}</code></li>
+            <li>Expanded: <code>{isExpanded}</code></li>
+            <li>Total clicks: <code>{clicks}</code></li>
+          </ul>
+        </div>
+      </div>
+    {/if}
+  </div>
+  
+  <div class="footer">
+    <small>🤖 AI Workspace Example Component</small>
+  </div>
+</div>
\ No newline at end of file
diff --git a/ai/workspace/components/example/component.js b/ai/workspace/components/example/component.js
new file mode 100644
index 000000000..185cfb12a
--- /dev/null
+++ b/ai/workspace/components/example/component.js
@@ -0,0 +1,83 @@
+import { defineComponent, getText } from '/packages/component/src/index.js';
+
+const template = await getText('./component.html');
+const css = await getText('./component.css');
+
+const defaultSettings = {
+  title: 'Example Component',
+  theme: 'primary',
+  count: 0,
+  disabled: false,
+};
+
+const defaultState = {
+  isExpanded: false,
+  clicks: 0,
+  message: 'Hello from AI Workspace!',
+};
+
+const createComponent = ({ self, state, settings, dispatchEvent }) => ({
+  increment() {
+    state.clicks.increment();
+    dispatchEvent('countChanged', {
+      count: state.clicks.get(),
+      component: 'example',
+    });
+  },
+
+  toggleExpanded() {
+    state.isExpanded.toggle();
+    console.log('Expanded state:', state.isExpanded.get());
+  },
+
+  updateMessage(newMessage) {
+    state.message.set(newMessage);
+  },
+
+  getStatus() {
+    return {
+      clicks: state.clicks.get(),
+      expanded: state.isExpanded.get(),
+      theme: settings.theme,
+      title: settings.title,
+    };
+  },
+});
+
+const events = {
+  'click .increment-btn': ({ self }) => {
+    self.increment();
+  },
+
+  'click .toggle-btn': ({ self }) => {
+    self.toggleExpanded();
+  },
+
+  'input .message-input': ({ state, value }) => {
+    state.message.set(value);
+  },
+};
+
+const onCreated = ({ state, settings }) => {
+  console.log('Example component created with settings:', settings);
+  state.clicks.set(settings.count || 0);
+};
+
+const onRendered = ({ self, isClient }) => {
+  if (isClient) {
+    console.log('Example component rendered in browser');
+    console.log('Component status:', self.getStatus());
+  }
+};
+
+export const ExampleComponent = defineComponent({
+  tagName: 'example',
+  template,
+  css,
+  defaultSettings,
+  defaultState,
+  createComponent,
+  events,
+  onCreated,
+  onRendered,
+});
diff --git a/ai/workspace/components/test-component/component.js b/ai/workspace/components/test-component/component.js
new file mode 100644
index 000000000..24df95241
--- /dev/null
+++ b/ai/workspace/components/test-component/component.js
@@ -0,0 +1,599 @@
+/**
+ * Test Component for MCP Debugging Environment
+ * Demonstrates various web component patterns and debugging scenarios
+ */
+
+class TestComponent extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this._counter = 0;
+    this._isExpanded = false;
+    this._theme = 'default';
+    this._data = [];
+    this._timerId = null;
+  }
+
+  static get observedAttributes() {
+    return ['theme', 'disabled', 'auto-increment'];
+  }
+
+  connectedCallback() {
+    this.render();
+    this.setupEventListeners();
+    this.dispatchEvent(
+      new CustomEvent('test-component-connected', {
+        detail: { counter: this._counter },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+
+    // Auto-increment if enabled
+    if (this.hasAttribute('auto-increment')) {
+      this.startAutoIncrement();
+    }
+  }
+
+  disconnectedCallback() {
+    this.stopAutoIncrement();
+    this.dispatchEvent(
+      new CustomEvent('test-component-disconnected', {
+        detail: { finalCounter: this._counter },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    switch (name) {
+      case 'theme':
+        this._theme = newValue || 'default';
+        break;
+      case 'disabled':
+        this.disabled = newValue !== null;
+        break;
+      case 'auto-increment':
+        if (newValue !== null) {
+          this.startAutoIncrement();
+        }
+        else {
+          this.stopAutoIncrement();
+        }
+        break;
+    }
+
+    if (this.shadowRoot) {
+      this.render();
+    }
+  }
+
+  render() {
+    this.shadowRoot.innerHTML = `
+      <style>
+        :host {
+          display: block;
+          padding: 20px;
+          border: 2px solid var(--border-color, #ccc);
+          border-radius: 8px;
+          font-family: system-ui, -apple-system, sans-serif;
+          transition: all 0.3s ease;
+          background: var(--bg-color, white);
+        }
+        
+        :host([theme="dark"]) {
+          --border-color: #555;
+          --bg-color: #2a2a2a;
+          --text-color: white;
+          --button-bg: #4a90e2;
+        }
+        
+        :host([theme="accent"]) {
+          --border-color: #ff6b6b;
+          --bg-color: #fff5f5;
+          --text-color: #333;
+          --button-bg: #ff6b6b;
+        }
+        
+        :host([disabled]) {
+          opacity: 0.6;
+          pointer-events: none;
+        }
+        
+        .header {
+          display: flex;
+          justify-content: space-between;
+          align-items: center;
+          margin-bottom: 16px;
+          padding-bottom: 12px;
+          border-bottom: 1px solid var(--border-color, #eee);
+        }
+        
+        .title {
+          font-size: 18px;
+          font-weight: 600;
+          color: var(--text-color, #333);
+        }
+        
+        .theme-badge {
+          background: var(--button-bg, #007bff);
+          color: white;
+          padding: 4px 8px;
+          border-radius: 4px;
+          font-size: 12px;
+          font-weight: 500;
+        }
+        
+        .counter-section {
+          background: var(--section-bg, #f8f9fa);
+          padding: 16px;
+          border-radius: 6px;
+          margin-bottom: 16px;
+          text-align: center;
+        }
+        
+        .counter-display {
+          font-size: 24px;
+          font-weight: bold;
+          color: var(--text-color, #333);
+          margin-bottom: 12px;
+        }
+        
+        .button-group {
+          display: flex;
+          gap: 8px;
+          justify-content: center;
+          flex-wrap: wrap;
+        }
+        
+        button {
+          background: var(--button-bg, #007bff);
+          color: white;
+          border: none;
+          padding: 8px 16px;
+          border-radius: 4px;
+          cursor: pointer;
+          font-size: 14px;
+          transition: all 0.2s ease;
+        }
+        
+        button:hover:not(:disabled) {
+          transform: translateY(-1px);
+          box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+        }
+        
+        button:active {
+          transform: translateY(0);
+        }
+        
+        button:disabled {
+          opacity: 0.6;
+          cursor: not-allowed;
+          transform: none !important;
+        }
+        
+        .secondary {
+          background: var(--secondary-bg, #6c757d);
+        }
+        
+        .danger {
+          background: var(--danger-bg, #dc3545);
+        }
+        
+        .success {
+          background: var(--success-bg, #28a745);
+        }
+        
+        .expandable-section {
+          border: 1px solid var(--border-color, #ddd);
+          border-radius: 6px;
+          overflow: hidden;
+          margin-bottom: 16px;
+        }
+        
+        .expand-header {
+          background: var(--header-bg, #f1f3f4);
+          padding: 12px 16px;
+          cursor: pointer;
+          display: flex;
+          justify-content: space-between;
+          align-items: center;
+          user-select: none;
+        }
+        
+        .expand-header:hover {
+          background: var(--header-hover-bg, #e8eaed);
+        }
+        
+        .expand-content {
+          padding: 16px;
+          display: ${this._isExpanded ? 'block' : 'none'};
+          background: var(--content-bg, white);
+        }
+        
+        .data-section {
+          background: var(--code-bg, #f8f9fa);
+          border: 1px solid var(--border-color, #e9ecef);
+          border-radius: 4px;
+          padding: 12px;
+          margin: 8px 0;
+        }
+        
+        .data-item {
+          padding: 8px;
+          margin: 4px 0;
+          background: white;
+          border-radius: 3px;
+          display: flex;
+          justify-content: space-between;
+          align-items: center;
+        }
+        
+        .status-indicator {
+          width: 12px;
+          height: 12px;
+          border-radius: 50%;
+          background: ${this._counter > 10 ? '#28a745' : this._counter > 5 ? '#ffc107' : '#dc3545'};
+          margin-right: 8px;
+        }
+        
+        .debug-info {
+          font-family: 'Courier New', monospace;
+          font-size: 12px;
+          background: var(--debug-bg, #f8f9fa);
+          padding: 8px;
+          border-radius: 4px;
+          margin-top: 12px;
+          white-space: pre-line;
+        }
+        
+        .slot-content {
+          border: 2px dashed var(--border-color, #ccc);
+          padding: 16px;
+          border-radius: 6px;
+          margin-top: 16px;
+          min-height: 40px;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          color: var(--text-color, #666);
+        }
+        
+        .auto-increment-indicator {
+          display: ${this.hasAttribute('auto-increment') ? 'inline-block' : 'none'};
+          background: #ffc107;
+          color: #333;
+          padding: 2px 6px;
+          border-radius: 3px;
+          font-size: 10px;
+          font-weight: 600;
+          margin-left: 8px;
+        }
+        
+        @keyframes pulse {
+          0%, 100% { opacity: 1; }
+          50% { opacity: 0.5; }
+        }
+        
+        .pulsing {
+          animation: pulse 1s infinite;
+        }
+      </style>
+      
+      <div class="header">
+        <div class="title">
+          🧪 Test Component
+          <span class="auto-increment-indicator">AUTO</span>
+        </div>
+        <div class="theme-badge">${this._theme}</div>
+      </div>
+      
+      <div class="counter-section">
+        <div class="counter-display">
+          <span class="status-indicator"></span>
+          Counter: ${this._counter}
+        </div>
+        <div class="button-group">
+          <button id="increment-btn">Increment (+1)</button>
+          <button id="increment-5-btn">Add 5</button>
+          <button id="reset-btn" class="secondary">Reset</button>
+          <button id="random-btn" class="success">Random</button>
+          <button id="error-btn" class="danger">Trigger Error</button>
+        </div>
+      </div>
+      
+      <div class="expandable-section">
+        <div class="expand-header" id="expand-header">
+          <span>📊 Data & State (Click to ${this._isExpanded ? 'collapse' : 'expand'})</span>
+          <span>${this._isExpanded ? '▲' : '▼'}</span>
+        </div>
+        <div class="expand-content">
+          <div class="data-section">
+            <strong>Internal State:</strong>
+            <div class="data-item">
+              <span>Counter: ${this._counter}</span>
+              <span>Type: ${typeof this._counter}</span>
+            </div>
+            <div class="data-item">
+              <span>Expanded: ${this._isExpanded}</span>
+              <span>Theme: ${this._theme}</span>
+            </div>
+            <div class="data-item">
+              <span>Data Items: ${this._data.length}</span>
+              <span>Auto-increment: ${this.hasAttribute('auto-increment')}</span>
+            </div>
+          </div>
+          
+          <button id="add-data-btn" class="success">Add Random Data</button>
+          <button id="clear-data-btn" class="danger">Clear Data</button>
+          
+          ${
+      this._data.length > 0
+        ? `
+            <div class="data-section">
+              <strong>Data Array:</strong>
+              ${
+          this._data.map((item, index) => `
+                <div class="data-item">
+                  <span>${index}: ${JSON.stringify(item)}</span>
+                  <button class="danger remove-data" data-index="${index}">×</button>
+                </div>
+              `).join('')
+        }
+            </div>
+          `
+        : ''
+    }
+        </div>
+      </div>
+      
+      <div class="slot-content">
+        <slot>🎯 Slot content will appear here</slot>
+      </div>
+      
+      <div class="debug-info">
+Debug Info:
+- Component ID: ${this.id || 'No ID set'}
+- Classes: ${this.className || 'No classes'}
+- Shadow DOM: ${this.shadowRoot ? 'Attached' : 'Not attached'}
+- Connected: ${this.isConnected}
+- Disabled: ${this.hasAttribute('disabled')}
+- Render time: ${new Date().toLocaleTimeString()}
+      </div>
+    `;
+  }
+
+  setupEventListeners() {
+    const shadowRoot = this.shadowRoot;
+
+    // Increment button
+    shadowRoot.getElementById('increment-btn')?.addEventListener('click', () => {
+      this.increment();
+    });
+
+    // Increment by 5
+    shadowRoot.getElementById('increment-5-btn')?.addEventListener('click', () => {
+      this.increment(5);
+    });
+
+    // Reset button
+    shadowRoot.getElementById('reset-btn')?.addEventListener('click', () => {
+      this.reset();
+    });
+
+    // Random button
+    shadowRoot.getElementById('random-btn')?.addEventListener('click', () => {
+      this.setCounter(Math.floor(Math.random() * 100));
+    });
+
+    // Error button (for testing error handling)
+    shadowRoot.getElementById('error-btn')?.addEventListener('click', () => {
+      this.triggerError();
+    });
+
+    // Expand/collapse
+    shadowRoot.getElementById('expand-header')?.addEventListener('click', () => {
+      this.toggleExpanded();
+    });
+
+    // Add data button
+    shadowRoot.getElementById('add-data-btn')?.addEventListener('click', () => {
+      this.addRandomData();
+    });
+
+    // Clear data button
+    shadowRoot.getElementById('clear-data-btn')?.addEventListener('click', () => {
+      this.clearData();
+    });
+
+    // Remove data buttons
+    shadowRoot.querySelectorAll('.remove-data').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        const index = parseInt(e.target.dataset.index);
+        this.removeData(index);
+      });
+    });
+  }
+
+  // Public API methods
+  increment(amount = 1) {
+    const oldValue = this._counter;
+    this._counter += amount;
+    this.render();
+    this.dispatchEvent(
+      new CustomEvent('counter-changed', {
+        detail: {
+          oldValue,
+          newValue: this._counter,
+          amount,
+        },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  reset() {
+    const oldValue = this._counter;
+    this._counter = 0;
+    this.render();
+    this.dispatchEvent(
+      new CustomEvent('counter-reset', {
+        detail: { oldValue },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  setCounter(value) {
+    const oldValue = this._counter;
+    this._counter = value;
+    this.render();
+    this.dispatchEvent(
+      new CustomEvent('counter-set', {
+        detail: { oldValue, newValue: value },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  toggleExpanded() {
+    this._isExpanded = !this._isExpanded;
+    this.render();
+    this.dispatchEvent(
+      new CustomEvent('section-toggled', {
+        detail: { expanded: this._isExpanded },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  addRandomData() {
+    const newItem = {
+      id: Date.now(),
+      value: Math.floor(Math.random() * 1000),
+      timestamp: new Date().toISOString(),
+      type: ['string', 'number', 'boolean'][Math.floor(Math.random() * 3)],
+    };
+
+    this._data.push(newItem);
+    this.render();
+    this.dispatchEvent(
+      new CustomEvent('data-added', {
+        detail: { item: newItem, total: this._data.length },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  clearData() {
+    const count = this._data.length;
+    this._data = [];
+    this.render();
+    this.dispatchEvent(
+      new CustomEvent('data-cleared', {
+        detail: { clearedCount: count },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  removeData(index) {
+    if (index >= 0 && index < this._data.length) {
+      const removed = this._data.splice(index, 1)[0];
+      this.render();
+      this.dispatchEvent(
+        new CustomEvent('data-removed', {
+          detail: { item: removed, index, remaining: this._data.length },
+          bubbles: true,
+          composed: true,
+        }),
+      );
+    }
+  }
+
+  startAutoIncrement() {
+    this.stopAutoIncrement();
+    this._timerId = setInterval(() => {
+      this.increment();
+    }, 2000);
+    this.dispatchEvent(
+      new CustomEvent('auto-increment-started', {
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  stopAutoIncrement() {
+    if (this._timerId) {
+      clearInterval(this._timerId);
+      this._timerId = null;
+      this.dispatchEvent(
+        new CustomEvent('auto-increment-stopped', {
+          bubbles: true,
+          composed: true,
+        }),
+      );
+    }
+  }
+
+  triggerError() {
+    this.dispatchEvent(
+      new CustomEvent('error-triggered', {
+        detail: {
+          message: 'Intentional test error',
+          timestamp: Date.now(),
+          counter: this._counter,
+        },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+
+    // Simulate an actual error for testing
+    setTimeout(() => {
+      throw new Error('Test component intentional error for debugging');
+    }, 100);
+  }
+
+  // Getters for debugging
+  get counter() {
+    return this._counter;
+  }
+
+  get theme() {
+    return this._theme;
+  }
+
+  get isExpanded() {
+    return this._isExpanded;
+  }
+
+  get data() {
+    return [...this._data]; // Return copy
+  }
+
+  get state() {
+    return {
+      counter: this._counter,
+      theme: this._theme,
+      expanded: this._isExpanded,
+      dataCount: this._data.length,
+      autoIncrement: this.hasAttribute('auto-increment'),
+      disabled: this.hasAttribute('disabled'),
+    };
+  }
+}
+
+// Register the component
+customElements.define('test-component', TestComponent);
+
+// Export for module usage
+export { TestComponent };
diff --git a/ai/workspace/debug-bridge.js b/ai/workspace/debug-bridge.js
new file mode 100644
index 000000000..fd9020d76
--- /dev/null
+++ b/ai/workspace/debug-bridge.js
@@ -0,0 +1,604 @@
+/**
+ * Debug Bridge - Browser-side debugging infrastructure for web components
+ * Provides MCP tool interface for component inspection and manipulation
+ */
+window.__debugBridge = {
+  ws: null,
+  componentRegistry: new WeakMap(),
+  eventListeners: new Map(),
+  mutationObservers: new Map(),
+
+  connect(url) {
+    this.ws = new WebSocket(url);
+
+    this.ws.onopen = () => {
+      console.log('🔗 Debug bridge connected to MCP server');
+    };
+
+    this.ws.onmessage = async (event) => {
+      const { type, tool, params, id } = JSON.parse(event.data);
+
+      if (type === 'mcp-tool-request') {
+        console.log(`🛠️ Executing tool: ${tool}`, params);
+        try {
+          const result = await this.handleToolRequest(tool, params);
+          this.ws.send(JSON.stringify({
+            type: 'mcp-tool-response',
+            id,
+            result,
+          }));
+        }
+        catch (error) {
+          this.ws.send(JSON.stringify({
+            type: 'mcp-tool-response',
+            id,
+            error: {
+              message: error.message,
+              stack: error.stack,
+              params,
+            },
+          }));
+        }
+      }
+    };
+
+    this.ws.onerror = (error) => {
+      console.error('❌ Debug bridge WebSocket error:', error);
+    };
+
+    // Auto-register components
+    this.setupComponentTracking();
+  },
+
+  setupComponentTracking() {
+    // Intercept customElements.define to track new component types
+    const originalDefine = customElements.define;
+    customElements.define = function(name, constructor, options) {
+      console.log(`📝 Registering component type: ${name}`);
+      originalDefine.call(this, name, constructor, options);
+
+      // Track all existing instances
+      setTimeout(() => {
+        document.querySelectorAll(name).forEach(el => {
+          window.__debugBridge.registerComponent(el);
+        });
+      }, 0);
+    };
+
+    // Monitor for new component instances
+    const observer = new MutationObserver((mutations) => {
+      mutations.forEach(mutation => {
+        mutation.addedNodes.forEach(node => {
+          if (node.nodeType === 1 && node.tagName.includes('-')) {
+            this.registerComponent(node);
+          }
+          // Also check for nested components
+          if (node.nodeType === 1 && node.querySelectorAll) {
+            node.querySelectorAll('*').forEach(child => {
+              if (child.tagName.includes('-')) {
+                this.registerComponent(child);
+              }
+            });
+          }
+        });
+      });
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+    });
+
+    // Register existing components
+    document.querySelectorAll('*').forEach(el => {
+      if (el.tagName.includes('-')) {
+        this.registerComponent(el);
+      }
+    });
+  },
+
+  registerComponent(element) {
+    if (this.componentRegistry.has(element)) { return; }
+
+    console.log(`🧩 Registering component instance: ${element.tagName.toLowerCase()}`);
+
+    const componentData = {
+      tagName: element.tagName.toLowerCase(),
+      shadowRoot: element.shadowRoot,
+      attributes: [...element.attributes].map(a => ({
+        name: a.name,
+        value: a.value,
+      })),
+      properties: {},
+      events: [],
+      mutations: [],
+      registeredAt: Date.now(),
+    };
+
+    this.componentRegistry.set(element, componentData);
+
+    // Set up mutation observer for shadow DOM
+    if (element.shadowRoot) {
+      const observer = new MutationObserver((mutations) => {
+        const data = this.componentRegistry.get(element);
+        if (data) {
+          data.mutations.push(...mutations.map(m => ({
+            type: m.type,
+            target: m.target.tagName || m.target.nodeName,
+            timestamp: Date.now(),
+            addedNodes: m.addedNodes.length,
+            removedNodes: m.removedNodes.length,
+            attributeName: m.attributeName,
+            oldValue: m.oldValue,
+          })));
+
+          // Keep only last 50 mutations
+          if (data.mutations.length > 50) {
+            data.mutations = data.mutations.slice(-50);
+          }
+        }
+      });
+
+      observer.observe(element.shadowRoot, {
+        childList: true,
+        attributes: true,
+        characterData: true,
+        subtree: true,
+        attributeOldValue: true,
+        characterDataOldValue: true,
+      });
+
+      this.mutationObservers.set(element, observer);
+    }
+  },
+
+  async handleToolRequest(tool, params) {
+    switch (tool) {
+      case 'inspect_component':
+        return this.inspectComponent(params.selector, params.depth);
+
+      case 'execute_in_component':
+        return this.executeInComponent(params.selector, params.code);
+
+      case 'monitor_events':
+        return this.monitorEvents(params.selector, params.events);
+
+      case 'get_computed_styles':
+        return this.getComputedStyles(params.selector, params.elementPath);
+
+      case 'mutation_history':
+        return this.getMutationHistory(params.selector, params.count);
+
+      case 'list_components':
+        return this.listComponents();
+
+      case 'query_shadow_dom':
+        return this.queryShadowDOM(params.selector, params.query);
+
+      case 'get_component_state':
+        return this.getComponentState(params.selector);
+
+      case 'take_screenshot':
+        return this.takeScreenshot(params.selector);
+
+      default:
+        throw new Error(`Unknown tool: ${tool}`);
+    }
+  },
+
+  // Enhanced $ function with shadow DOM piercing
+  $(selector, root = document) {
+    // If it's already an element, return it
+    if (selector instanceof Element) { return selector; }
+
+    // Try normal query first
+    let element = root.querySelector(selector);
+    if (element) { return element; }
+
+    // Deep search through shadow DOMs
+    const walker = document.createTreeWalker(
+      root,
+      NodeFilter.SHOW_ELEMENT,
+      {
+        acceptNode: (node) => {
+          if (node.shadowRoot) {
+            const found = node.shadowRoot.querySelector(selector);
+            if (found) {
+              element = found;
+              return NodeFilter.FILTER_REJECT;
+            }
+          }
+          return NodeFilter.FILTER_SKIP;
+        },
+      },
+    );
+
+    while (walker.nextNode() && !element) {
+      // Walker handles the traversal
+    }
+
+    return element;
+  },
+
+  inspectComponent(selector, depth = 3) {
+    const element = this.$(selector);
+    if (!element) { throw new Error(`Component not found: ${selector}`); }
+
+    const data = this.componentRegistry.get(element);
+    if (!data) {
+      // Register it now if not already registered
+      this.registerComponent(element);
+    }
+
+    const result = {
+      tagName: element.tagName.toLowerCase(),
+      id: element.id,
+      classes: [...element.classList],
+      attributes: [...element.attributes].map(a => ({
+        name: a.name,
+        value: a.value,
+      })),
+      properties: this.getComponentProperties(element),
+      shadowRoot: null,
+      lightDOM: this.serializeDOM(element, Math.min(depth, 2)),
+      boundingRect: element.getBoundingClientRect(),
+      registeredEvents: data ? data.events.length : 0,
+      mutationCount: data ? data.mutations.length : 0,
+    };
+
+    if (element.shadowRoot && depth > 0) {
+      result.shadowRoot = this.serializeDOM(element.shadowRoot, depth - 1);
+    }
+
+    return result;
+  },
+
+  executeInComponent(selector, code) {
+    const element = this.$(selector);
+    if (!element) { throw new Error(`Component not found: ${selector}`); }
+
+    // Create safe execution context
+    const context = {
+      host: element,
+      shadow: element.shadowRoot,
+      $: (sel) => this.$(sel, element.shadowRoot || element),
+      $$: (sel) => {
+        const results = [];
+        if (element.shadowRoot) {
+          results.push(...element.shadowRoot.querySelectorAll(sel));
+        }
+        results.push(...element.querySelectorAll(sel));
+        return results;
+      },
+      document: element.shadowRoot || document,
+      getComputedStyle: window.getComputedStyle.bind(window),
+      console: {
+        log: (...args) => {
+          console.log('[Component Execution]', ...args);
+          return args;
+        },
+      },
+    };
+
+    // Execute with error handling
+    try {
+      const fn = new Function(...Object.keys(context), `"use strict"; return (${code})`);
+      return fn(...Object.values(context));
+    }
+    catch (error) {
+      throw new Error(`Execution failed: ${error.message}`);
+    }
+  },
+
+  monitorEvents(selector, events) {
+    const element = this.$(selector);
+    if (!element) { throw new Error(`Component not found: ${selector}`); }
+
+    const key = `${selector}:${events.join(',')}`;
+
+    // Remove existing listeners
+    if (this.eventListeners.has(key)) {
+      const oldListeners = this.eventListeners.get(key);
+      oldListeners.forEach(({ event, handler }) => {
+        element.removeEventListener(event, handler);
+      });
+    }
+
+    // Add new listeners
+    const listeners = events.map(event => {
+      const handler = (e) => {
+        const eventData = {
+          type: 'event-triggered',
+          selector,
+          event,
+          detail: {
+            type: e.type,
+            target: e.target.tagName || e.target.nodeName,
+            currentTarget: e.currentTarget.tagName || e.currentTarget.nodeName,
+            composed: e.composed,
+            bubbles: e.bubbles,
+            detail: e.detail,
+            timestamp: Date.now(),
+            path: e.composedPath ? e.composedPath().map(n => n.tagName || n.nodeName).slice(0, 5) : [],
+          },
+        };
+
+        console.log('📡 Event captured:', eventData);
+
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+          this.ws.send(JSON.stringify(eventData));
+        }
+      };
+
+      element.addEventListener(event, handler, true);
+      return { event, handler };
+    });
+
+    this.eventListeners.set(key, listeners);
+    return { status: 'monitoring', events, selector, listenersActive: listeners.length };
+  },
+
+  getComputedStyles(selector, elementPath) {
+    const component = this.$(selector);
+    if (!component) { throw new Error(`Component not found: ${selector}`); }
+
+    let element = component;
+
+    // Navigate to specific element within shadow DOM
+    if (elementPath) {
+      if (component.shadowRoot) {
+        element = component.shadowRoot.querySelector(elementPath);
+      }
+      else {
+        element = component.querySelector(elementPath);
+      }
+      if (!element) { throw new Error(`Element not found: ${elementPath}`); }
+    }
+
+    const computed = window.getComputedStyle(element);
+    const styles = {};
+
+    // Get relevant computed styles (not all 300+ properties)
+    const importantProps = [
+      'display',
+      'position',
+      'width',
+      'height',
+      'margin',
+      'padding',
+      'border',
+      'background',
+      'color',
+      'font-family',
+      'font-size',
+      'font-weight',
+      'z-index',
+      'opacity',
+      'transform',
+      'transition',
+      'box-shadow',
+      'border-radius',
+      'overflow',
+      'visibility',
+    ];
+
+    importantProps.forEach(prop => {
+      styles[prop] = computed.getPropertyValue(prop);
+    });
+
+    // Get CSS custom properties
+    const customProps = {};
+    for (let i = 0; i < computed.length; i++) {
+      const prop = computed[i];
+      if (prop.startsWith('--')) {
+        customProps[prop] = computed.getPropertyValue(prop);
+      }
+    }
+
+    return {
+      selector,
+      elementPath,
+      tagName: element.tagName.toLowerCase(),
+      styles,
+      customProperties: customProps,
+      boundingBox: element.getBoundingClientRect(),
+    };
+  },
+
+  getMutationHistory(selector, count = 10) {
+    const element = this.$(selector);
+    if (!element) { throw new Error(`Component not found: ${selector}`); }
+
+    const data = this.componentRegistry.get(element);
+    if (!data) { throw new Error(`Component not registered: ${selector}`); }
+
+    return {
+      selector,
+      mutations: data.mutations.slice(-count),
+      total: data.mutations.length,
+      registeredAt: data.registeredAt,
+    };
+  },
+
+  listComponents() {
+    const components = [];
+
+    document.querySelectorAll('*').forEach(el => {
+      if (el.tagName.includes('-')) {
+        const data = this.componentRegistry.get(el);
+        components.push({
+          tagName: el.tagName.toLowerCase(),
+          id: el.id || null,
+          classes: [...el.classList],
+          hasShadowRoot: !!el.shadowRoot,
+          isRegistered: !!data,
+          boundingRect: el.getBoundingClientRect(),
+        });
+      }
+    });
+
+    return {
+      total: components.length,
+      components,
+    };
+  },
+
+  queryShadowDOM(selector, query) {
+    const component = this.$(selector);
+    if (!component) { throw new Error(`Component not found: ${selector}`); }
+
+    if (!component.shadowRoot) {
+      throw new Error(`Component has no shadow root: ${selector}`);
+    }
+
+    const elements = [...component.shadowRoot.querySelectorAll(query)];
+
+    return {
+      selector,
+      query,
+      found: elements.length,
+      elements: elements.map(el => ({
+        tagName: el.tagName.toLowerCase(),
+        id: el.id || null,
+        classes: [...el.classList],
+        attributes: [...el.attributes].map(a => ({ name: a.name, value: a.value })),
+        textContent: el.textContent.trim().substring(0, 100),
+        boundingRect: el.getBoundingClientRect(),
+      })),
+    };
+  },
+
+  getComponentState(selector) {
+    const element = this.$(selector);
+    if (!element) { throw new Error(`Component not found: ${selector}`); }
+
+    // Try to get component state through common patterns
+    const state = {
+      properties: this.getComponentProperties(element),
+      attributes: [...element.attributes].map(a => ({ name: a.name, value: a.value })),
+      internalState: null,
+      methods: [],
+    };
+
+    // Look for common state patterns
+    if (element._state) { state.internalState = element._state; }
+    if (element.state) { state.internalState = element.state; }
+    if (element.data) { state.internalState = element.data; }
+
+    // Get available methods
+    const proto = Object.getPrototypeOf(element);
+    Object.getOwnPropertyNames(proto).forEach(name => {
+      if (
+        typeof element[name] === 'function'
+        && !name.startsWith('_')
+        && name !== 'constructor'
+        && !['addEventListener', 'removeEventListener', 'dispatchEvent'].includes(name)
+      ) {
+        state.methods.push(name);
+      }
+    });
+
+    return state;
+  },
+
+  takeScreenshot(selector) {
+    const element = this.$(selector);
+    if (!element) { throw new Error(`Component not found: ${selector}`); }
+
+    // Basic implementation - would need html2canvas for actual screenshots
+    const rect = element.getBoundingClientRect();
+
+    return {
+      selector,
+      boundingBox: {
+        top: rect.top,
+        left: rect.left,
+        width: rect.width,
+        height: rect.height,
+        right: rect.right,
+        bottom: rect.bottom,
+      },
+      viewport: {
+        width: window.innerWidth,
+        height: window.innerHeight,
+      },
+      note: 'For actual screenshots, html2canvas library would be needed',
+    };
+  },
+
+  // Helper methods
+  serializeDOM(root, maxDepth, currentDepth = 0) {
+    if (currentDepth >= maxDepth) { return { type: 'truncated', maxDepthReached: true }; }
+
+    const children = [];
+    for (const child of root.children || []) {
+      children.push({
+        tagName: child.tagName.toLowerCase(),
+        id: child.id || null,
+        classes: [...child.classList],
+        attributes: [...child.attributes].map(a => ({
+          name: a.name,
+          value: a.value,
+        })),
+        textContent: child.textContent ? child.textContent.trim().substring(0, 100) : '',
+        children: this.serializeDOM(child, maxDepth, currentDepth + 1),
+      });
+    }
+
+    return {
+      type: root.nodeType === 11 ? 'shadow-root' : 'element',
+      childCount: children.length,
+      children,
+    };
+  },
+
+  getComponentProperties(element) {
+    const props = {};
+    const proto = Object.getPrototypeOf(element);
+
+    // Get all property descriptors
+    Object.getOwnPropertyNames(proto).forEach(name => {
+      if (name === 'constructor') { return; }
+
+      try {
+        const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+        if (descriptor && (descriptor.get || descriptor.value !== undefined)) {
+          const value = element[name];
+
+          // Only include serializable values
+          if (
+            typeof value === 'string'
+            || typeof value === 'number'
+            || typeof value === 'boolean'
+            || value === null
+            || value === undefined
+          ) {
+            props[name] = value;
+          }
+          else if (typeof value === 'object' && value !== element) {
+            props[name] = '[Object]';
+          }
+          else if (typeof value === 'function') {
+            props[name] = '[Function]';
+          }
+        }
+      }
+      catch (e) {
+        // Some properties might throw
+        props[name] = '[Error accessing property]';
+      }
+    });
+
+    return props;
+  },
+};
+
+// Auto-connect when script loads
+document.addEventListener('DOMContentLoaded', () => {
+  console.log('🚀 Debug bridge initializing...');
+
+  // Make $ function globally available
+  window.$ = window.__debugBridge.$.bind(window.__debugBridge);
+
+  console.log('✅ Debug bridge ready');
+});
diff --git a/ai/workspace/mcp-tools.js b/ai/workspace/mcp-tools.js
new file mode 100644
index 000000000..f9fd9a07b
--- /dev/null
+++ b/ai/workspace/mcp-tools.js
@@ -0,0 +1,375 @@
+/**
+ * MCP Tool Definitions for Web Component Debugging
+ * These schemas define the available debugging tools for AI agents
+ */
+
+export const debugTools = {
+  inspect_component: {
+    description: "Inspect a web component's structure, attributes, shadow DOM, and current state",
+    parameters: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description:
+            "CSS selector, component ID, or tag name to find the component. Examples: '#my-component', 'ui-dropdown', '.my-class'",
+        },
+        depth: {
+          type: 'number',
+          description: 'How deep to traverse shadow DOM tree (default: 3, max recommended: 5)',
+          default: 3,
+          minimum: 1,
+          maximum: 10,
+        },
+      },
+      required: ['selector'],
+    },
+    examples: [
+      {
+        description: 'Inspect a component by ID',
+        parameters: { selector: '#main-dropdown', depth: 2 },
+      },
+      {
+        description: 'Deep inspection of component structure',
+        parameters: { selector: 'test-component', depth: 4 },
+      },
+    ],
+  },
+
+  execute_in_component: {
+    description:
+      "Execute JavaScript code within a component's context with access to shadow DOM and component internals",
+    parameters: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'Component selector to execute code within',
+        },
+        code: {
+          type: 'string',
+          description:
+            'JavaScript code to execute. Available variables: host (component element), shadow (shadowRoot), $ (shadow-aware query), $$ (query all), document (shadow document), console',
+        },
+      },
+      required: ['selector', 'code'],
+    },
+    examples: [
+      {
+        description: "Check component's internal counter value",
+        parameters: {
+          selector: '#counter-component',
+          code: "host.counter || host._counter || 'Counter not found'",
+        },
+      },
+      {
+        description: 'Find all buttons in shadow DOM',
+        parameters: {
+          selector: 'ui-modal',
+          code: "$$('button').length",
+        },
+      },
+      {
+        description: "Get component's current state",
+        parameters: {
+          selector: 'test-component',
+          code: '({ counter: host.counter, shadowHTML: shadow.innerHTML.length, classList: [...host.classList] })',
+        },
+      },
+    ],
+  },
+
+  monitor_events: {
+    description: 'Start monitoring specific events on a component. Events will be streamed in real-time via WebSocket',
+    parameters: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'Component selector to monitor',
+        },
+        events: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Array of event names to monitor. Common events: click, change, input, custom events',
+        },
+      },
+      required: ['selector', 'events'],
+    },
+    examples: [
+      {
+        description: 'Monitor user interactions',
+        parameters: {
+          selector: '#interactive-component',
+          events: ['click', 'mouseover', 'focus'],
+        },
+      },
+      {
+        description: 'Monitor custom component events',
+        parameters: {
+          selector: 'ui-dropdown',
+          events: ['selection-changed', 'dropdown-opened', 'dropdown-closed'],
+        },
+      },
+    ],
+  },
+
+  get_computed_styles: {
+    description: 'Get computed CSS styles for a component or element within its shadow DOM',
+    parameters: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'Component selector',
+        },
+        elementPath: {
+          type: 'string',
+          description:
+            "Optional CSS selector for element within component's shadow DOM. If not provided, styles of the component itself are returned",
+        },
+      },
+      required: ['selector'],
+    },
+    examples: [
+      {
+        description: "Get component's own styles",
+        parameters: { selector: 'test-component' },
+      },
+      {
+        description: 'Get styles of button inside component',
+        parameters: {
+          selector: 'test-component',
+          elementPath: 'button',
+        },
+      },
+      {
+        description: 'Get styles of specific element',
+        parameters: {
+          selector: 'ui-modal',
+          elementPath: '.modal-header .close-button',
+        },
+      },
+    ],
+  },
+
+  mutation_history: {
+    description: "Get recent DOM mutations within a component's shadow DOM for debugging dynamic changes",
+    parameters: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'Component selector',
+        },
+        count: {
+          type: 'number',
+          description: 'Number of recent mutations to retrieve (default: 10, max: 50)',
+          default: 10,
+          minimum: 1,
+          maximum: 50,
+        },
+      },
+      required: ['selector'],
+    },
+    examples: [
+      {
+        description: 'Get last 5 DOM changes',
+        parameters: { selector: 'dynamic-component', count: 5 },
+      },
+      {
+        description: 'Get full mutation history',
+        parameters: { selector: 'test-component', count: 50 },
+      },
+    ],
+  },
+
+  list_components: {
+    description: 'List all web components currently on the page with their basic information',
+    parameters: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+    examples: [
+      {
+        description: 'Get overview of all components',
+        parameters: {},
+      },
+    ],
+  },
+
+  query_shadow_dom: {
+    description: "Query for elements within a component's shadow DOM using CSS selectors",
+    parameters: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'Component selector',
+        },
+        query: {
+          type: 'string',
+          description: "CSS selector to find elements within the component's shadow DOM",
+        },
+      },
+      required: ['selector', 'query'],
+    },
+    examples: [
+      {
+        description: 'Find all buttons in component',
+        parameters: {
+          selector: 'ui-modal',
+          query: 'button',
+        },
+      },
+      {
+        description: 'Find elements with specific class',
+        parameters: {
+          selector: 'test-component',
+          query: '.interactive-element',
+        },
+      },
+      {
+        description: 'Find form inputs',
+        parameters: {
+          selector: 'ui-form',
+          query: 'input, select, textarea',
+        },
+      },
+    ],
+  },
+
+  get_component_state: {
+    description: "Get a component's internal state, properties, and available methods for debugging",
+    parameters: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'Component selector',
+        },
+      },
+      required: ['selector'],
+    },
+    examples: [
+      {
+        description: "Get component's current state",
+        parameters: { selector: 'stateful-component' },
+      },
+      {
+        description: 'Check component properties and methods',
+        parameters: { selector: '#dynamic-widget' },
+      },
+    ],
+  },
+
+  take_screenshot: {
+    description:
+      'Get component dimensions and position information (note: actual screenshot requires additional libraries)',
+    parameters: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'string',
+          description: 'Component selector',
+        },
+      },
+      required: ['selector'],
+    },
+    examples: [
+      {
+        description: 'Get component layout info',
+        parameters: { selector: 'ui-modal' },
+      },
+    ],
+  },
+};
+
+/**
+ * Tool usage guidelines for AI agents
+ */
+export const usageGuidelines = {
+  debugging_workflow: [
+    "1. Start with 'list_components' to see all available components",
+    "2. Use 'inspect_component' to understand structure and current state",
+    "3. Use 'execute_in_component' to test specific functionality",
+    "4. Monitor behavior with 'monitor_events' for interactive debugging",
+    "5. Check styling issues with 'get_computed_styles'",
+    "6. Track dynamic changes with 'mutation_history'",
+  ],
+
+  best_practices: {
+    selectors: [
+      'Use specific selectors when possible (IDs or tag names)',
+      "For custom components, use tag names like 'ui-dropdown' or 'test-component'",
+      "Fallback to class selectors '.my-component' if needed",
+    ],
+
+    code_execution: [
+      'Keep executed code simple and focused',
+      'Use the provided context variables (host, shadow, $, $$)',
+      'Return serializable data (avoid circular references)',
+      'Use console.log for debugging output',
+    ],
+
+    event_monitoring: [
+      'Start with common events: click, change, input',
+      'Add custom component events based on component documentation',
+      'Monitor for short periods to avoid overwhelming the system',
+    ],
+  },
+
+  common_patterns: {
+    finding_components: 'list_components() → inspect_component(selector)',
+    debugging_interactions: "monitor_events(selector, ['click']) → execute_in_component(selector, code)",
+    styling_issues: 'inspect_component(selector) → get_computed_styles(selector, elementPath)',
+    state_debugging: "get_component_state(selector) → execute_in_component(selector, 'return host.someProperty')",
+  },
+};
+
+/**
+ * Event types that components commonly emit
+ */
+export const commonEvents = {
+  user_interactions: [
+    'click',
+    'dblclick',
+    'mousedown',
+    'mouseup',
+    'mouseover',
+    'mouseout',
+    'focus',
+    'blur',
+    'keydown',
+    'keyup',
+    'input',
+    'change',
+    'submit',
+  ],
+
+  semantic_ui_components: [
+    'selection-changed',
+    'item-selected',
+    'dropdown-opened',
+    'dropdown-closed',
+    'modal-opened',
+    'modal-closed',
+    'tab-changed',
+    'accordion-expanded',
+    'form-validated',
+    'field-changed',
+    'button-clicked',
+  ],
+
+  lifecycle_events: [
+    'component-created',
+    'component-rendered',
+    'component-destroyed',
+    'state-changed',
+    'settings-updated',
+    'data-loaded',
+  ],
+};
+
+export default debugTools;
diff --git a/ai/workspace/public/component.html b/ai/workspace/public/component.html
new file mode 100644
index 000000000..2b5ab7938
--- /dev/null
+++ b/ai/workspace/public/component.html
@@ -0,0 +1,447 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Component Tester - AI Workspace</title>
+    <link rel="stylesheet" href="/dist/semantic-ui.css">
+    <style>
+        body {
+            font-family: system-ui, -apple-system, sans-serif;
+            margin: 0;
+            padding: 0;
+            background: #f8f9fa;
+            display: flex;
+            height: 100vh;
+        }
+        
+        .main-area {
+            flex: 1;
+            display: flex;
+            flex-direction: column;
+        }
+        
+        .header {
+            background: white;
+            padding: 1rem;
+            border-bottom: 1px solid #e1e5e9;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+        }
+        
+        .component-area {
+            flex: 1;
+            padding: 2rem;
+            overflow: auto;
+        }
+        
+        .debug-panel {
+            width: 350px;
+            background: #2d3748;
+            color: white;
+            display: flex;
+            flex-direction: column;
+            overflow: hidden;
+        }
+        
+        .debug-header {
+            background: #1a202c;
+            padding: 1rem;
+            border-bottom: 1px solid #4a5568;
+        }
+        
+        .debug-content {
+            flex: 1;
+            overflow: auto;
+            padding: 1rem;
+        }
+        
+        .debug-section {
+            margin-bottom: 1.5rem;
+        }
+        
+        .debug-section h4 {
+            margin: 0 0 0.5rem 0;
+            color: #a0aec0;
+            font-size: 0.8rem;
+            text-transform: uppercase;
+            font-weight: 600;
+        }
+        
+        .debug-output {
+            background: #1a202c;
+            border-radius: 4px;
+            padding: 0.75rem;
+            font-family: 'Courier New', monospace;
+            font-size: 0.8rem;
+            white-space: pre-wrap;
+            max-height: 200px;
+            overflow-y: auto;
+            border: 1px solid #4a5568;
+        }
+        
+        .debug-button {
+            background: #4299e1;
+            color: white;
+            border: none;
+            padding: 0.5rem 1rem;
+            border-radius: 4px;
+            cursor: pointer;
+            font-size: 0.8rem;
+            margin-right: 0.5rem;
+            margin-bottom: 0.5rem;
+        }
+        
+        .debug-button:hover {
+            background: #3182ce;
+        }
+        
+        .debug-input {
+            background: #1a202c;
+            border: 1px solid #4a5568;
+            color: white;
+            padding: 0.5rem;
+            border-radius: 4px;
+            width: 100%;
+            font-family: 'Courier New', monospace;
+            font-size: 0.8rem;
+        }
+        
+        .component-info {
+            background: #f7fafc;
+            border-left: 4px solid #4299e1;
+            padding: 1rem;
+            margin-bottom: 1rem;
+        }
+        
+        .error-overlay {
+            position: fixed;
+            top: 0;
+            left: 0;
+            right: 0;
+            bottom: 0;
+            background: rgba(0,0,0,0.9);
+            color: white;
+            padding: 2rem;
+            font-family: 'Courier New', monospace;
+            white-space: pre-wrap;
+            overflow: auto;
+            z-index: 9999;
+            display: none;
+        }
+        
+        .hidden {
+            display: none !important;
+        }
+    </style>
+</head>
+<body>
+    <div class="main-area">
+        <div class="header">
+            <div>
+                <h2 id="component-title">Component Tester</h2>
+                <small id="component-path">No component loaded</small>
+            </div>
+            <div>
+                <button id="reload-btn" class="debug-button">Reload Component</button>
+                <button id="toggle-debug" class="debug-button">Toggle Debug Panel</button>
+            </div>
+        </div>
+        
+        <div class="component-area">
+            <div id="component-info" class="component-info hidden">
+                <strong>Component Information:</strong>
+                <div id="component-details"></div>
+            </div>
+            
+            <div id="component-container">
+                <p>Loading component...</p>
+            </div>
+        </div>
+    </div>
+    
+    <div class="debug-panel" id="debug-panel">
+        <div class="debug-header">
+            <h3>🛠️ Debug Tools</h3>
+        </div>
+        
+        <div class="debug-content">
+            <div class="debug-section">
+                <h4>Query Tester</h4>
+                <input type="text" 
+                       id="query-input" 
+                       class="debug-input" 
+                       placeholder="Enter selector (e.g., .button, $$('ui-component'))"
+                       value="$$('*')">
+                <br><br>
+                <button id="run-query" class="debug-button">Run Query</button>
+                <button id="run-deep-query" class="debug-button">Run Deep ($$)</button>
+                <div id="query-output" class="debug-output">Run a query to see results...</div>
+            </div>
+            
+            <div class="debug-section">
+                <h4>Component Inspector</h4>
+                <button id="inspect-components" class="debug-button">Find All Components</button>
+                <button id="inspect-state" class="debug-button">Inspect State</button>
+                <div id="component-output" class="debug-output">Click a button to inspect components...</div>
+            </div>
+            
+            <div class="debug-section">
+                <h4>Shadow DOM Explorer</h4>
+                <button id="explore-shadows" class="debug-button">Find Shadow Roots</button>
+                <button id="explore-deep" class="debug-button">Deep DOM Structure</button>
+                <div id="shadow-output" class="debug-output">Explore shadow DOM structure...</div>
+            </div>
+            
+            <div class="debug-section">
+                <h4>Console Log</h4>
+                <button id="clear-log" class="debug-button">Clear</button>
+                <div id="console-log" class="debug-output">Console output will appear here...</div>
+            </div>
+        </div>
+    </div>
+    
+    <div id="error-overlay" class="error-overlay">
+        <h3>Build Error</h3>
+        <div id="error-content"></div>
+        <p><button onclick="document.getElementById('error-overlay').style.display='none'" 
+                   style="background: #e53e3e; color: white; border: none; padding: 0.5rem 1rem; border-radius: 4px; cursor: pointer;">
+            Close
+        </button></p>
+    </div>
+
+    <script type="module">
+        import { $, $$, Query, exportGlobals } from '/packages/query/src/index.js';
+        
+        // Make Query tools available globally for debugging
+        exportGlobals();
+        window.Query = Query;
+        
+        // Get component name from URL
+        const urlParams = new URLSearchParams(window.location.search);
+        const componentName = urlParams.get('name') || 'example';
+        
+        // Update UI
+        document.getElementById('component-title').textContent = `Testing: ${componentName}`;
+        document.getElementById('component-path').textContent = `components/${componentName}/`;
+        
+        // Console logging override
+        const consoleLog = document.getElementById('console-log');
+        const originalLog = console.log;
+        const originalError = console.error;
+        const originalWarn = console.warn;
+        
+        function addToLog(type, ...args) {
+            const timestamp = new Date().toLocaleTimeString();
+            const message = args.map(arg => 
+                typeof arg === 'object' ? JSON.stringify(arg, null, 2) : String(arg)
+            ).join(' ');
+            
+            consoleLog.textContent += `[${timestamp}] ${type.toUpperCase()}: ${message}\n`;
+            consoleLog.scrollTop = consoleLog.scrollHeight;
+        }
+        
+        console.log = (...args) => {
+            originalLog.apply(console, args);
+            addToLog('log', ...args);
+        };
+        
+        console.error = (...args) => {
+            originalError.apply(console, args);
+            addToLog('error', ...args);
+        };
+        
+        console.warn = (...args) => {
+            originalWarn.apply(console, args);
+            addToLog('warn', ...args);
+        };
+        
+        // Load and display component
+        async function loadComponent() {
+            const container = document.getElementById('component-container');
+            const componentInfo = document.getElementById('component-info');
+            const componentDetails = document.getElementById('component-details');
+            
+            try {
+                // Try to load the component
+                const componentModule = await import(`/components/${componentName}/component.js`);
+                
+                // Show component info
+                componentInfo.classList.remove('hidden');
+                componentDetails.innerHTML = `
+                    <div>Name: <code>${componentName}</code></div>
+                    <div>Path: <code>components/${componentName}/</code></div>
+                    <div>Module loaded successfully</div>
+                `;
+                
+                // Create component in container
+                container.innerHTML = `
+                    <${componentName}></${componentName}>
+                `;
+                
+                console.log('Component loaded successfully:', componentName);
+                
+                // Wait a moment for component to initialize
+                setTimeout(() => {
+                    inspectLoadedComponent();
+                }, 100);
+                
+            } catch (error) {
+                console.error('Failed to load component:', error);
+                container.innerHTML = `
+                    <div style="color: red; padding: 1rem; background: #fee; border: 1px solid #fcc; border-radius: 4px;">
+                        <strong>Failed to load component: ${componentName}</strong><br>
+                        Error: ${error.message}<br><br>
+                        Make sure the component files exist at:<br>
+                        <code>components/${componentName}/component.js</code><br>
+                        <code>components/${componentName}/component.html</code><br>
+                        <code>components/${componentName}/component.css</code>
+                    </div>
+                `;
+            }
+        }
+        
+        function inspectLoadedComponent() {
+            const componentOutput = document.getElementById('component-output');
+            try {
+                const components = $$(`${componentName}`);
+                if (components.length > 0) {
+                    const component = components.eq(0);
+                    const instance = component.component();
+                    const dataContext = component.dataContext();
+                    
+                    componentOutput.textContent = `Found ${components.length} instance(s)\n`;
+                    componentOutput.textContent += `Component instance: ${!!instance}\n`;
+                    componentOutput.textContent += `Data context available: ${!!dataContext}\n`;
+                    
+                    if (dataContext) {
+                        componentOutput.textContent += `State keys: ${Object.keys(dataContext.state || {}).join(', ')}\n`;
+                        componentOutput.textContent += `Settings keys: ${Object.keys(dataContext.settings || {}).join(', ')}\n`;
+                    }
+                } else {
+                    componentOutput.textContent = 'No component instances found';
+                }
+            } catch (error) {
+                componentOutput.textContent = `Error inspecting component: ${error.message}`;
+            }
+        }
+        
+        // Debug panel controls
+        document.getElementById('toggle-debug').addEventListener('click', () => {
+            const panel = document.getElementById('debug-panel');
+            panel.classList.toggle('hidden');
+        });
+        
+        document.getElementById('reload-btn').addEventListener('click', () => {
+            location.reload();
+        });
+        
+        document.getElementById('clear-log').addEventListener('click', () => {
+            consoleLog.textContent = '';
+        });
+        
+        // Query tester
+        document.getElementById('run-query').addEventListener('click', () => {
+            const input = document.getElementById('query-input').value;
+            const output = document.getElementById('query-output');
+            try {
+                const result = $(input);
+                output.textContent = `$(${input})\nFound ${result.length} elements\n`;
+                result.each((index, el) => {
+                    output.textContent += `${index}: ${el.tagName.toLowerCase()}${el.className ? '.' + el.className : ''}${el.id ? '#' + el.id : ''}\n`;
+                });
+            } catch (error) {
+                output.textContent = `Error: ${error.message}`;
+            }
+        });
+        
+        document.getElementById('run-deep-query').addEventListener('click', () => {
+            const input = document.getElementById('query-input').value;
+            const output = document.getElementById('query-output');
+            try {
+                const result = $$(input);
+                output.textContent = `$$(${input})\nFound ${result.length} elements (deep search)\n`;
+                result.each((index, el) => {
+                    output.textContent += `${index}: ${el.tagName.toLowerCase()}${el.className ? '.' + el.className : ''}${el.id ? '#' + el.id : ''}\n`;
+                });
+            } catch (error) {
+                output.textContent = `Error: ${error.message}`;
+            }
+        });
+        
+        // Component inspector
+        document.getElementById('inspect-components').addEventListener('click', () => {
+            inspectLoadedComponent();
+        });
+        
+        document.getElementById('inspect-state').addEventListener('click', () => {
+            const output = document.getElementById('component-output');
+            try {
+                const components = $$(`${componentName}`);
+                if (components.length > 0) {
+                    const context = components.eq(0).dataContext();
+                    output.textContent = JSON.stringify({
+                        state: context?.state || 'No state',
+                        settings: context?.settings || 'No settings'
+                    }, null, 2);
+                } else {
+                    output.textContent = 'No components found to inspect';
+                }
+            } catch (error) {
+                output.textContent = `Error: ${error.message}`;
+            }
+        });
+        
+        // Shadow DOM explorer
+        document.getElementById('explore-shadows').addEventListener('click', () => {
+            const output = document.getElementById('shadow-output');
+            try {
+                const shadowRoots = [];
+                $$('*').each((index, el) => {
+                    if (el.shadowRoot) {
+                        shadowRoots.push(el.tagName.toLowerCase());
+                    }
+                });
+                output.textContent = `Found ${shadowRoots.length} shadow roots:\n${shadowRoots.join('\n')}`;
+            } catch (error) {
+                output.textContent = `Error: ${error.message}`;
+            }
+        });
+        
+        document.getElementById('explore-deep').addEventListener('click', () => {
+            const output = document.getElementById('shadow-output');
+            try {
+                const allElements = $$('*');
+                const structure = {};
+                allElements.each((index, el) => {
+                    const tag = el.tagName.toLowerCase();
+                    structure[tag] = (structure[tag] || 0) + 1;
+                });
+                output.textContent = `Deep DOM structure (${allElements.length} total elements):\n`;
+                Object.entries(structure)
+                    .sort((a, b) => b[1] - a[1])
+                    .forEach(([tag, count]) => {
+                        output.textContent += `${tag}: ${count}\n`;
+                    });
+            } catch (error) {
+                output.textContent = `Error: ${error.message}`;
+            }
+        });
+        
+        // Query input enter key support
+        document.getElementById('query-input').addEventListener('keypress', (e) => {
+            if (e.key === 'Enter') {
+                document.getElementById('run-query').click();
+            }
+        });
+        
+        // Load component on page load
+        loadComponent();
+        
+        console.log('🛠️ AI Workspace loaded with Query debugging tools');
+        console.log('Available globals: $, $$, Query');
+        console.log(`Testing component: ${componentName}`);
+    </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/ai/workspace/public/index.html b/ai/workspace/public/index.html
new file mode 100644
index 000000000..4521baf0a
--- /dev/null
+++ b/ai/workspace/public/index.html
@@ -0,0 +1,384 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AI Workspace - MCP Debugging Environment</title>
+    <style>
+        body {
+            font-family: system-ui, -apple-system, sans-serif;
+            margin: 0;
+            padding: 2rem;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            min-height: 100vh;
+            color: white;
+        }
+        .container {
+            max-width: 1000px;
+            margin: 0 auto;
+            background: rgba(255, 255, 255, 0.95);
+            color: #333;
+            padding: 2rem;
+            border-radius: 16px;
+            box-shadow: 0 20px 40px rgba(0,0,0,0.1);
+            backdrop-filter: blur(10px);
+        }
+        .header {
+            text-align: center;
+            margin-bottom: 3rem;
+        }
+        .header h1 {
+            font-size: 2.5rem;
+            margin: 0;
+            background: linear-gradient(135deg, #667eea, #764ba2);
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+            background-clip: text;
+        }
+        .status-indicators {
+            display: flex;
+            justify-content: center;
+            gap: 2rem;
+            margin: 2rem 0;
+            flex-wrap: wrap;
+        }
+        .status-card {
+            background: white;
+            padding: 1rem;
+            border-radius: 8px;
+            box-shadow: 0 4px 12px rgba(0,0,0,0.1);
+            text-align: center;
+            min-width: 120px;
+        }
+        .status-indicator {
+            width: 12px;
+            height: 12px;
+            border-radius: 50%;
+            margin: 0 auto 0.5rem;
+        }
+        .status-connected { background: #28a745; }
+        .status-disconnected { background: #dc3545; }
+        .status-pending { background: #ffc107; }
+        .grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+            gap: 2rem;
+            margin-top: 2rem;
+        }
+        .card {
+            background: white;
+            padding: 1.5rem;
+            border-radius: 12px;
+            box-shadow: 0 8px 24px rgba(0,0,0,0.1);
+            transition: transform 0.2s ease, box-shadow 0.2s ease;
+        }
+        .card:hover {
+            transform: translateY(-4px);
+            box-shadow: 0 12px 32px rgba(0,0,0,0.15);
+        }
+        .card h3 {
+            margin-top: 0;
+            color: #2c3e50;
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+        }
+        .component-link {
+            display: block;
+            padding: 1rem;
+            margin: 0.5rem 0;
+            background: linear-gradient(135deg, #f8f9fa, #e9ecef);
+            text-decoration: none;
+            color: #333;
+            border-radius: 8px;
+            transition: all 0.2s ease;
+            border-left: 4px solid #667eea;
+        }
+        .component-link:hover {
+            background: linear-gradient(135deg, #e9ecef, #dee2e6);
+            transform: translateX(4px);
+        }
+        .code {
+            background: #f8f9fa;
+            padding: 0.25rem 0.5rem;
+            border-radius: 4px;
+            font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', monospace;
+            font-size: 0.9em;
+            border: 1px solid #e9ecef;
+        }
+        .mcp-tools {
+            background: linear-gradient(135deg, #667eea, #764ba2);
+            color: white;
+            padding: 1.5rem;
+            border-radius: 12px;
+            margin: 2rem 0;
+        }
+        .mcp-tools h3 {
+            margin-top: 0;
+            color: white;
+        }
+        .tool-list {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+            gap: 1rem;
+            margin-top: 1rem;
+        }
+        .tool-item {
+            background: rgba(255,255,255,0.1);
+            padding: 0.75rem;
+            border-radius: 6px;
+            backdrop-filter: blur(10px);
+        }
+        .demo-component {
+            margin: 2rem 0;
+            padding: 2rem;
+            border: 2px dashed #dee2e6;
+            border-radius: 12px;
+            background: #f8f9fa;
+        }
+        .connection-status {
+            position: fixed;
+            top: 20px;
+            right: 20px;
+            background: rgba(255,255,255,0.9);
+            padding: 0.5rem 1rem;
+            border-radius: 20px;
+            font-size: 0.8rem;
+            font-weight: 600;
+            backdrop-filter: blur(10px);
+            box-shadow: 0 4px 12px rgba(0,0,0,0.1);
+        }
+    </style>
+</head>
+<body>
+    <div class="connection-status" id="connection-status">
+        🔌 Connecting to MCP...
+    </div>
+
+    <div class="container">
+        <div class="header">
+            <h1>🧪 AI Workspace</h1>
+            <p>MCP-Enabled Web Component Debugging Environment</p>
+        </div>
+
+        <div class="status-indicators">
+            <div class="status-card">
+                <div class="status-indicator status-pending" id="ws-status"></div>
+                <div>WebSocket</div>
+                <small id="ws-text">Connecting...</small>
+            </div>
+            <div class="status-card">
+                <div class="status-indicator status-pending" id="debug-status"></div>
+                <div>Debug Bridge</div>
+                <small id="debug-text">Initializing...</small>
+            </div>
+            <div class="status-card">
+                <div class="status-indicator status-pending" id="component-status"></div>
+                <div>Components</div>
+                <small id="component-text">Scanning...</small>
+            </div>
+        </div>
+
+        <div class="mcp-tools">
+            <h3>🛠️ Available MCP Tools</h3>
+            <p>AI agents can use these tools to inspect and debug web components:</p>
+            <div class="tool-list">
+                <div class="tool-item">
+                    <strong>inspect_component</strong><br>
+                    <small>Deep component analysis</small>
+                </div>
+                <div class="tool-item">
+                    <strong>execute_in_component</strong><br>
+                    <small>Run code in component context</small>
+                </div>
+                <div class="tool-item">
+                    <strong>monitor_events</strong><br>
+                    <small>Real-time event streaming</small>
+                </div>
+                <div class="tool-item">
+                    <strong>query_shadow_dom</strong><br>
+                    <small>Shadow DOM querying</small>
+                </div>
+                <div class="tool-item">
+                    <strong>get_computed_styles</strong><br>
+                    <small>CSS inspection</small>
+                </div>
+                <div class="tool-item">
+                    <strong>list_components</strong><br>
+                    <small>Component discovery</small>
+                </div>
+            </div>
+        </div>
+
+        <div class="demo-component">
+            <h3>🎯 Live Test Component</h3>
+            <p>Interact with this component while an AI agent debugs it in real-time:</p>
+            <test-component id="demo-test" theme="default">
+                <p>🎪 This is slotted content inside the test component!</p>
+            </test-component>
+        </div>
+
+        <div class="grid">
+            <div class="card">
+                <h3>🚀 Quick Start</h3>
+                <ol>
+                    <li>Create components in <span class="code">components/my-component/</span></li>
+                    <li>Use MCP tools to inspect and debug</li>
+                    <li>Test with real-time event monitoring</li>
+                    <li>Iterate based on debugging insights</li>
+                </ol>
+            </div>
+
+            <div class="card">
+                <h3>🧩 Component Tools</h3>
+                <div class="component-list">
+                    <a href="/public/component.html" class="component-link">
+                        📝 Component Tester
+                    </a>
+                    <a href="/public/component.html?name=test-component" class="component-link">
+                        🧪 Test Component Demo
+                    </a>
+                    <a href="/public/component.html?name=example" class="component-link">
+                        🎯 Example Component
+                    </a>
+                </div>
+            </div>
+
+            <div class="card">
+                <h3>📊 Debug Features</h3>
+                <ul>
+                    <li>🔍 Shadow DOM inspection</li>
+                    <li>⚡ Real-time event monitoring</li>
+                    <li>🎨 CSS computed styles analysis</li>
+                    <li>🧠 Component state introspection</li>
+                    <li>💾 DOM mutation tracking</li>
+                    <li>🎯 Code execution in component context</li>
+                </ul>
+            </div>
+
+            <div class="card">
+                <h3>📚 Documentation</h3>
+                <p>Access comprehensive component development guides:</p>
+                <ul>
+                    <li><a href="/mcp-tools.js" target="_blank">MCP Tools Reference</a></li>
+                    <li><a href="/ai/guides/component-generation-instructions.md" target="_blank">Component Guide</a></li>
+                    <li><a href="/ai/specialized/query-system-guide.md" target="_blank">Query System</a></li>
+                </ul>
+            </div>
+        </div>
+
+        <div class="card" style="margin-top: 2rem;">
+            <h3>🔍 Discovered Components</h3>
+            <div id="components-list">
+                <p>Scanning for components...</p>
+            </div>
+        </div>
+    </div>
+
+    <script type="module" src="/components/test-component/component.js"></script>
+    <script type="module">
+        // Status management
+        function updateStatus(type, status, text) {
+            const indicator = document.getElementById(`${type}-status`);
+            const textEl = document.getElementById(`${type}-text`);
+            
+            indicator.className = `status-indicator status-${status}`;
+            if (textEl) textEl.textContent = text;
+        }
+
+        function updateConnectionStatus(text, color = '#666') {
+            const status = document.getElementById('connection-status');
+            status.textContent = text;
+            status.style.color = color;
+        }
+
+        // Component discovery
+        async function loadComponentsList() {
+            try {
+                const response = await fetch('/components/');
+                if (!response.ok) throw new Error('Failed to fetch');
+                
+                const html = await response.text();
+                const parser = new DOMParser();
+                const doc = parser.parseFromString(html, 'text/html');
+                const links = doc.querySelectorAll('a[href]');
+                
+                const components = Array.from(links)
+                    .map(link => link.getAttribute('href'))
+                    .filter(href => href && href !== '../' && href.endsWith('/'))
+                    .map(href => href.replace('/', ''));
+
+                const container = document.getElementById('components-list');
+                if (components.length > 0) {
+                    container.innerHTML = components.map(name => 
+                        `<a href="/public/component.html?name=${name}" class="component-link">
+                            🧩 ${name} - <small>Test this component</small>
+                        </a>`
+                    ).join('');
+                    updateStatus('component', 'connected', `${components.length} found`);
+                } else {
+                    container.innerHTML = '<p>No components found. Create your first component!</p>';
+                    updateStatus('component', 'disconnected', 'None found');
+                }
+            } catch (error) {
+                document.getElementById('components-list').innerHTML = 
+                    '<p>Could not load components list.</p>';
+                updateStatus('component', 'disconnected', 'Error loading');
+            }
+        }
+
+        // Debug bridge monitoring
+        function checkDebugBridge() {
+            if (window.__debugBridge) {
+                updateStatus('debug', 'connected', 'Ready');
+                
+                // Monitor WebSocket connection
+                const checkWS = () => {
+                    if (window.__debugBridge.ws) {
+                        const ws = window.__debugBridge.ws;
+                        switch (ws.readyState) {
+                            case WebSocket.CONNECTING:
+                                updateStatus('ws', 'pending', 'Connecting...');
+                                updateConnectionStatus('🔌 Connecting to MCP...', '#ffc107');
+                                break;
+                            case WebSocket.OPEN:
+                                updateStatus('ws', 'connected', 'Connected');
+                                updateConnectionStatus('✅ MCP Connected', '#28a745');
+                                break;
+                            case WebSocket.CLOSING:
+                            case WebSocket.CLOSED:
+                                updateStatus('ws', 'disconnected', 'Disconnected');
+                                updateConnectionStatus('❌ MCP Disconnected', '#dc3545');
+                                break;
+                        }
+                    } else {
+                        updateStatus('ws', 'pending', 'Initializing...');
+                    }
+                };
+                
+                setInterval(checkWS, 1000);
+                checkWS();
+            } else {
+                updateStatus('debug', 'pending', 'Loading...');
+                setTimeout(checkDebugBridge, 500);
+            }
+        }
+
+        // Initialize
+        document.addEventListener('DOMContentLoaded', () => {
+            console.log('🚀 AI Workspace initializing...');
+            loadComponentsList();
+            checkDebugBridge();
+            
+            // Listen for component events
+            document.addEventListener('counter-changed', (e) => {
+                console.log('📊 Counter changed:', e.detail);
+            });
+            
+            document.addEventListener('section-toggled', (e) => {
+                console.log('📖 Section toggled:', e.detail);
+            });
+        });
+    </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/docs/src/pages/api/query/attributes.mdx b/docs/src/pages/api/query/attributes.mdx
index 673ca9311..5c88148b4 100755
--- a/docs/src/pages/api/query/attributes.mdx
+++ b/docs/src/pages/api/query/attributes.mdx
@@ -89,3 +89,91 @@ $('selector').removeAttr(attributeName)
 // Remove the 'disabled' attribute from all buttons
 $('button').removeAttr('disabled');
 ```
+
+## data
+
+Gets or sets data attributes on elements. Data attributes are HTML attributes that start with `data-` and are commonly used to store custom data.
+
+### Syntax
+
+#### Get All Data Attributes
+```javascript
+$('selector').data()
+```
+
+#### Get Specific Data Attribute
+```javascript
+$('selector').data(key)
+```
+
+#### Set Data Attribute
+```javascript
+$('selector').data(key, value)
+```
+
+### Parameters
+| Name  | Type   | Description                    |
+|-------|--------|---------------------------------|
+| key   | string | The data attribute key (without 'data-' prefix) |
+| value | string | The value to set               |
+
+### Returns
+
+#### Get All Data Attributes
+- **Single Element** An object containing all data attributes.
+- **Multiple Elements** An array of objects, one for each matched element.
+
+#### Get Specific Data Attribute
+- **Single Element** The data attribute value.
+- **Multiple Elements** An array of values, one for each matched element.
+
+#### Set Data Attribute
+[Query object](/query/basic#the-query-object) (for chaining).
+
+### Usage
+
+#### Get All Data Attributes
+```javascript
+// HTML: <div data-user-id="123" data-role="admin"></div>
+const allData = $('div').data();
+console.log(allData); // { userId: "123", role: "admin" }
+```
+
+#### Get Specific Data Attribute
+```javascript
+// HTML: <div data-user-id="123"></div>
+const userId = $('div').data('userId');
+console.log(userId); // "123"
+```
+
+#### Set Data Attribute
+```javascript
+// Set a data attribute
+$('div').data('theme', 'dark');
+// Results in: <div data-theme="dark"></div>
+```
+
+#### Working with Multiple Elements
+```javascript
+// HTML: 
+// <div data-id="1" data-name="Alice"></div>
+// <div data-id="2" data-name="Bob"></div>
+
+// Get specific attribute from multiple elements
+const ids = $('div').data('id');
+console.log(ids); // ["1", "2"]
+
+// Get all data from multiple elements
+const allData = $('div').data();
+console.log(allData); // [{ id: "1", name: "Alice" }, { id: "2", name: "Bob" }]
+
+// Set data on multiple elements
+$('div').data('active', 'true');
+// Both divs now have data-active="true"
+```
+
+### Notes
+
+- Data attribute keys are automatically converted from camelCase to kebab-case in the HTML (e.g., `userId` becomes `data-user-id`)
+- When retrieving data, kebab-case attribute names are converted back to camelCase object keys
+- Data attributes are always stored and retrieved as strings
diff --git a/docs/src/pages/api/query/dimensions.mdx b/docs/src/pages/api/query/dimensions.mdx
index cf2b2809d..dbc415c93 100755
--- a/docs/src/pages/api/query/dimensions.mdx
+++ b/docs/src/pages/api/query/dimensions.mdx
@@ -247,3 +247,128 @@ console.log(imageNaturalHeight);
 const divNaturalHeight = $('div.content').naturalHeight();
 console.log(divNaturalHeight);
 ```
+
+## clippingParent
+
+Get the element that clips (crops) each element's visual bounds based on overflow properties.
+
+### Syntax
+```javascript
+$('selector').clippingParent()
+```
+
+### Returns
+A new [Query object](/api/query/basic#the-query-object) containing the clipping parent elements.
+
+### Usage
+
+#### Basic Clipping Detection
+```javascript
+// Find what element clips a positioned element
+const $tooltip = $('.tooltip');
+const $clipper = $tooltip.clippingParent();
+
+// Check if element is clipped by its container
+if ($clipper[0] !== document.documentElement) {
+  console.log('Element is clipped by:', $clipper[0]);
+}
+```
+
+#### Working with Scroll Containers
+```javascript
+// Find the scrollable container that clips content
+const $content = $('.overflow-content');
+const $scrollContainer = $content.clippingParent();
+
+// Adjust positioning to avoid clipping
+$scrollContainer.css('overflow', 'visible');
+```
+
+#### Multiple Elements
+```javascript
+// Get clipping parents for multiple elements
+$('.positioned-elements').each((el, index) => {
+  const $el = $(el);
+  const $clipper = $el.clippingParent();
+  console.log(`Element ${index} is clipped by:`, $clipper[0]);
+});
+```
+
+> **Clipping Detection** Returns `document.documentElement` when no clipping parent is found. Useful for positioning tooltips, dropdowns, and other overlay elements.
+
+## containingParent
+
+Get the element that establishes the positioning context for each element (where `offsetTop`/`offsetLeft` are relative to).
+
+> **Why not `offsetParent`?** `offsetParent` will often return an element that is **different** than the value `offsetTop` and `offsetLeft` are relative to. This is because values like `transform`, `will-change`, `filter` can all create new positioning contexts.
+
+
+### Syntax
+
+#### Calculate Modern Positioning Context
+```javascript
+$('selector').containingParent()
+$('selector').containingParent({ calculate: true })
+```
+
+#### Use Browser's offsetParent
+```javascript
+$('selector').containingParent({ calculate: false })
+```
+
+### Parameters
+| Name      | Type    | Description                                                      |
+|-----------|---------|------------------------------------------------------------------|
+| calculate | boolean | Whether to calculate containing parent using modern CSS properties (default: true) |
+
+### Returns
+A new [Query object](/api/query/basic#the-query-object) containing the containing parent elements.
+
+### Usage
+
+#### Modern Positioning Context Detection
+```javascript
+// Find the actual positioning context (includes transform, filter, etc.)
+const $absoluteEl = $('.absolute-positioned');
+const $container = $absoluteEl.containingParent();
+
+// Position element relative to its containing parent
+const containerRect = $container[0].getBoundingClientRect();
+$absoluteEl.css({
+  top: containerRect.height / 2,
+  left: containerRect.width / 2
+});
+```
+
+#### Browser's Native offsetParent
+```javascript
+// Get browser's reported offsetParent (legacy behavior)
+const $element = $('.positioned-element');
+const $offsetParent = $element.containingParent({ calculate: false });
+
+if ($offsetParent[0]) {
+  console.log('Browser offsetParent:', $offsetParent[0]);
+}
+```
+
+#### Fixed Position Elements
+```javascript
+// Fixed elements have no containing parent
+const $fixed = $('.fixed-positioned');
+const $container = $fixed.containingParent();
+
+if ($container[0] === undefined) {
+  console.log('Fixed element has no containing parent');
+}
+```
+
+#### Transform and Filter Detection
+```javascript
+// Elements with transforms create new positioning contexts
+const $transformed = $('.transformed-element');
+const $transformContainer = $transformed.containingParent();
+
+// Useful for accurately calculating positions
+const rect = $transformContainer[0].getBoundingClientRect();
+console.log('Transform container bounds:', rect);
+```
diff --git a/docs/src/pages/api/query/dom-manipulation.mdx b/docs/src/pages/api/query/dom-manipulation.mdx
index 23a1c8186..591ab332e 100755
--- a/docs/src/pages/api/query/dom-manipulation.mdx
+++ b/docs/src/pages/api/query/dom-manipulation.mdx
@@ -257,3 +257,83 @@ const $template = $('#item-template').clone();
 $('#container').append($template);
 ```
 
+## reverse
+
+Reverses the order of the elements in the current set.
+
+### Syntax
+```javascript
+$('selector').reverse()
+```
+
+### Returns
+A new [Query object](/api/query/basic#the-query-object) containing the reversed elements.
+
+### Usage
+```javascript
+// Reverse the order of list items
+const $reversed = $('ul li').reverse();
+$('ul').empty().append($reversed);
+```
+
+## slice
+
+Returns a shallow copy of a portion of the elements into a new Query object.
+
+### Syntax
+```javascript
+$('selector').slice(start, end)
+```
+
+### Parameters
+| Name  | Type   | Description                                                                 |
+|-------|--------|-----------------------------------------------------------------------------|
+| start | number | The beginning index of the specified portion of the collection (optional)  |
+| end   | number | The end index of the specified portion of the collection (optional, exclusive) |
+
+### Returns
+A new [Query object](/api/query/basic#the-query-object) containing the sliced elements.
+
+### Usage
+
+#### Basic Slicing
+```javascript
+// Get elements 2-4 from a list of items
+const $items = $('.item');
+const $sliced = $items.slice(1, 4); // Gets items at index 1, 2, 3
+
+// Get all elements from index 2 onwards
+const $fromIndex = $items.slice(2);
+
+// Get the last 2 elements using negative indices
+const $lastTwo = $items.slice(-2);
+```
+
+#### Working with Multiple Elements
+```javascript
+// Slice and manipulate a portion of elements
+$('.card').slice(0, 3).addClass('featured');
+
+// Process elements in batches
+const $allItems = $('.item');
+const firstBatch = $allItems.slice(0, 5);
+const secondBatch = $allItems.slice(5, 10);
+
+firstBatch.addClass('batch-one');
+secondBatch.addClass('batch-two');
+```
+
+#### Shadow DOM
+```javascript
+// Slice user posts in a user-profile component
+const $posts = $$('user-profile').find('.user-post');
+const $recentPosts = $posts.slice(0, 3);
+$recentPosts.addClass('recent');
+```
+
+### Notes
+- Returns the same instance when called on an empty collection
+- Supports negative indices like `Array.prototype.slice`
+- Creates a new Query object, enabling method chaining
+- Does not modify the original Query object
+
diff --git a/docs/src/pages/api/query/size-and-position.mdx b/docs/src/pages/api/query/size-and-position.mdx
deleted file mode 100755
index 2012dd9a3..000000000
--- a/docs/src/pages/api/query/size-and-position.mdx
+++ /dev/null
@@ -1,116 +0,0 @@
----
-layout: '@layouts/Guide.astro'
-pageType: 'API Reference'
-title: Query - Size & Position
-icon: move
-description: API reference for Query methods related to element dimensions and positioning
----
-
-Size and position methods in Query allow you to get information about element dimensions, scroll positions, and their position in the DOM.
-
-## count
-
-Get the number of elements in the Query object.
-
-### Syntax
-```javascript
-$('selector').count()
-```
-
-### Returns
-`number` - The number of elements in the Query object.
-
-### Usage
-```javascript
-const paragraphCount = $('p').count();
-console.log(`There are ${paragraphCount} paragraphs on the page.`);
-```
-
-> **Quick Count** `count()` is a convenient way to get the number of matched elements without converting to an array.
-
-## index
-
-Get the index of an element in the set of matched elements.
-
-### Syntax
-```javascript
-$('selector').index()
-```
-
-### Returns
-`number` - The index of the first element within the Query object relative to its sibling elements, or -1 if not found.
-
-### Usage
-```javascript
-const index = $('li.active').index();
-console.log(`The active list item is at index ${index}`);
-```
-
-> **DOM Position** `index()` is useful for determining the position of an element among its siblings.
-
-## offsetParent
-
-Get the closest positioned ancestor element.
-
-### Syntax
-```javascript
-$('selector').offsetParent(options)
-```
-
-### Parameters
-| Name    | Type   | Description                           |
-|---------|--------|---------------------------------------|
-| options | Object | Configuration options for the method  |
-
-### Returns
-[Query object](/api/query/basic#the-query-object) containing the offset parent element(s).
-
-### Usage
-```javascript
-const offsetParent = $('.child-element').offsetParent();
-console.log('Offset parent:', offsetParent.get(0));
-```
-
-> **Positioning Context** `offsetParent()` is particularly useful when working with absolutely positioned elements.
-
-## naturalWidth
-
-Get the natural width of an element, particularly useful for images.
-
-### Syntax
-```javascript
-$('selector').naturalWidth()
-```
-
-### Returns
-- **Single Element** The natural width of the element in pixels.
-- **Multiple Elements** An array of natural widths, one for each matched element.
-
-### Usage
-```javascript
-const imgNaturalWidth = $('img').naturalWidth();
-console.log('Natural width of the image:', imgNaturalWidth);
-```
-
-> **Element Dimensions** This method works by creating a clone of the element, positioning it off-screen, and measuring its dimensions. While accurate, it can cause a reflow in the document.
-
-## naturalHeight
-
-Get the natural height of an element, particularly useful for images.
-
-### Syntax
-```javascript
-$('selector').naturalHeight()
-```
-
-### Returns
-- **Single Element** The natural height of the element in pixels.
-- **Multiple Elements** An array of natural heights, one for each matched element.
-
-### Usage
-```javascript
-const imgNaturalHeight = $('img').naturalHeight();
-console.log('Natural height of the image:', imgNaturalHeight);
-```
-
-> **Element Dimensions** Like `naturalWidth()`, this method creates an off-screen clone to measure dimensions, which may cause a reflow.
diff --git a/docs/src/pages/api/query/utilities.mdx b/docs/src/pages/api/query/utilities.mdx
index d6a77b740..c21158f47 100755
--- a/docs/src/pages/api/query/utilities.mdx
+++ b/docs/src/pages/api/query/utilities.mdx
@@ -49,31 +49,6 @@ console.log(`The active list item is at index ${index}`);
 ```
 
 
-## offsetParent
-
-Get the closest positioned ancestor element.
-
-> **Edge-Case Improvements** `offsetParent()` handles some [edge cases}(https://issues.chromium.org/issues/41131675) that prevent the naive use of `el.offsetParent`
-
-### Syntax
-```javascript
-$('selector').offsetParent(options)
-```
-
-### Parameters
-| Name    | Type   | Description                           |
-|---------|--------|---------------------------------------|
-| options | Object | Configuration options for the method  |
-
-### Returns
-[Query object](/api/query/basic#the-query-object) containing the offset parent element(s).
-
-### Usage
-```javascript
-const offsetParent = $('.child-element').offsetParent();
-console.log('Offset parent:', offsetParent.get(0));
-```
-
 ## Element Access Methods
 
 These methods provide access to individual elements in a Query collection.
diff --git a/internal-packages/scripts/src/build-ai-workspace.js b/internal-packages/scripts/src/build-ai-workspace.js
new file mode 100644
index 000000000..479873001
--- /dev/null
+++ b/internal-packages/scripts/src/build-ai-workspace.js
@@ -0,0 +1,184 @@
+import * as esbuild from 'esbuild';
+import fs from 'fs/promises';
+import { resolve } from 'path';
+import { WebSocketServer } from 'ws';
+import { build } from './lib/build.js';
+
+const BASE_DIR = process.env.BASE_DIR || process.cwd();
+const WORKSPACE_DIR = resolve(BASE_DIR, 'ai/workspace');
+
+/*
+  MCP-enabled debugging environment for AI workspace
+  Sets up WebSocket server for MCP tools and esbuild serve with debug injection
+*/
+export const buildAIWorkspace = async ({
+  serve = false,
+  port = 8080,
+  wsPort = 8081,
+  host = 'localhost',
+  buildDeps = false,
+  watch = false,
+} = {}) => {
+  if (serve) {
+    console.log('🚀 Starting AI Workspace with MCP debugging...');
+
+    // Set up WebSocket server for MCP tool communication
+    const wss = new WebSocketServer({ port: wsPort });
+    const connections = new Set();
+
+    console.log(`🔌 MCP WebSocket server running on ws://${host}:${wsPort}`);
+
+    wss.on('connection', (ws) => {
+      connections.add(ws);
+      console.log('🔗 Debug bridge connected');
+
+      ws.on('close', () => {
+        connections.delete(ws);
+        console.log('🔌 Debug bridge disconnected');
+      });
+
+      // Handle MCP tool requests from agents
+      ws.on('message', async (data) => {
+        try {
+          const message = JSON.parse(data);
+
+          if (message.type === 'mcp-tool-request') {
+            console.log(`🛠️ Agent tool request: ${message.tool}`);
+
+            // Forward to browser debug bridge
+            for (const conn of connections) {
+              if (conn !== ws && conn.readyState === 1) {
+                conn.send(data);
+              }
+            }
+          }
+          else if (message.type === 'mcp-tool-response') {
+            // Forward response back to requesting agent
+            for (const conn of connections) {
+              if (conn !== ws && conn.readyState === 1) {
+                conn.send(data);
+              }
+            }
+          }
+          else if (message.type === 'event-triggered') {
+            // Broadcast events to all connected agents
+            console.log(`📡 Component event: ${message.event} on ${message.selector}`);
+            for (const conn of connections) {
+              if (conn !== ws && conn.readyState === 1) {
+                conn.send(data);
+              }
+            }
+          }
+        }
+        catch (error) {
+          console.error('❌ WebSocket message error:', error);
+        }
+      });
+    });
+
+    // esbuild plugin to inject debug bridge
+    const debugBridgePlugin = {
+      name: 'debug-bridge-injector',
+      setup(build) {
+        build.onLoad({ filter: /\.html$/ }, async (args) => {
+          let content = await fs.readFile(args.path, 'utf8');
+
+          // Inject debug bridge script before </body>
+          const injection = `
+            <script src="/debug-bridge.js"></script>
+            <script>
+              // Auto-connect debug bridge when page loads
+              document.addEventListener('DOMContentLoaded', () => {
+                window.__debugBridge.connect('ws://${host}:${wsPort}');
+              });
+            </script>
+          `;
+
+          content = content.replace('</body>', injection + '</body>');
+          return { contents: content, loader: 'html' };
+        });
+      },
+    };
+
+    try {
+      const context = await esbuild.context({
+        entryPoints: [
+          resolve(WORKSPACE_DIR, 'public/index.html'),
+          resolve(WORKSPACE_DIR, 'debug-bridge.js'),
+          resolve(WORKSPACE_DIR, 'mcp-tools.js'),
+        ],
+        bundle: false,
+        format: 'esm',
+        outdir: resolve(WORKSPACE_DIR, '.esbuild'),
+        plugins: [debugBridgePlugin],
+        logLevel: 'info',
+        loader: {
+          '.html': 'text',
+          '.css': 'text',
+          '.js': 'js',
+          '.ts': 'ts',
+        },
+      });
+
+      if (watch) {
+        await context.watch();
+        console.log('👀 File watching enabled');
+      }
+
+      const result = await context.serve({
+        port,
+        host,
+        servedir: WORKSPACE_DIR,
+      });
+
+      console.log(`\n✅ AI Workspace Ready!`);
+      console.log(`📡 Web server: http://${result.host}:${result.port}`);
+      console.log(`🔌 MCP WebSocket: ws://${host}:${wsPort}`);
+      console.log(`📁 Serving from: ${WORKSPACE_DIR}`);
+      console.log(`\n🎯 Quick Links:`);
+      console.log(`   • Main page: http://localhost:${port}/public/`);
+      console.log(`   • Component tester: http://localhost:${port}/public/component.html`);
+      console.log(`   • Test component: http://localhost:${port}/public/component.html?name=test-component`);
+      console.log(`\n💡 MCP Tools Available:`);
+      console.log(`   • inspect_component - Deep component analysis`);
+      console.log(`   • execute_in_component - Run code in component context`);
+      console.log(`   • monitor_events - Real-time event streaming`);
+      console.log(`   • list_components - See all components on page`);
+      console.log(`   • See mcp-tools.js for complete tool reference`);
+
+      // Keep the process alive
+      return new Promise(() => {
+        // Graceful shutdown handling
+        process.on('SIGINT', () => {
+          console.log('\n🛑 Shutting down AI workspace...');
+          wss.close();
+          context.dispose();
+          process.exit(0);
+        });
+      });
+    }
+    catch (error) {
+      console.error('❌ Failed to start workspace:', error);
+      wss.close();
+      return { success: false, error };
+    }
+  }
+
+  return { success: true };
+};
+
+// Handle direct execution of this script
+if (import.meta.url === `file://${process.argv[1]}`) {
+  (async function() {
+    const serve = process.argv.includes('--serve');
+    const port = process.argv.includes('--port')
+      ? parseInt(process.argv[process.argv.indexOf('--port') + 1])
+      : 8080;
+
+    return buildAIWorkspace({
+      serve,
+      port,
+      watch: serve, // Enable watch mode when serving
+    });
+  })();
+}
diff --git a/internal-packages/scripts/src/index.js b/internal-packages/scripts/src/index.js
index ed4865585..9528463a8 100644
--- a/internal-packages/scripts/src/index.js
+++ b/internal-packages/scripts/src/index.js
@@ -2,11 +2,12 @@
 export * from './lib/index.js';
 
 /* Builders */
+export { buildAIWorkspace } from './build-ai-workspace.js';
 export { buildBundle } from './build-bundle.js';
 export { buildCDN } from './build-cdn.js';
 export { buildESM } from './build-esm.js';
-export { buildUIDeps } from './build-ui-deps.js';
 export { buildUIComponents } from './build-ui-components.js';
+export { buildUIDeps } from './build-ui-deps.js';
 
 /* Watch */
 export { watch } from './watch.js';
diff --git a/package-lock.json b/package-lock.json
index 7dfc92ccb..a58a93ec1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -39,7 +39,8 @@
         "simple-git-hooks": "^2.12.1",
         "underscore": "^1.13.7",
         "vitest": "^3.0.9",
-        "wireit": "^0.14.11"
+        "wireit": "^0.14.11",
+        "ws": "^8.18.2"
       }
     },
     "internal-packages/esbuild-callback": {
@@ -8029,7 +8030,9 @@
       }
     },
     "node_modules/ws": {
-      "version": "8.18.1",
+      "version": "8.18.2",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.18.2.tgz",
+      "integrity": "sha512-DMricUmwGZUVr++AEAe2uiVM7UoO9MAVZMDu05UQOaUII0lp+zOzLLU4Xqh/JvTqklB1T4uELaaPBKyjE1r4fQ==",
       "dev": true,
       "license": "MIT",
       "engines": {
diff --git a/package.json b/package.json
index ec8a68074..444509476 100755
--- a/package.json
+++ b/package.json
@@ -113,6 +113,7 @@
   "scripts": {
     "build": "wireit",
     "dev": "wireit",
+    "dev:workspace": "node ./internal-packages/scripts/src/build-ai-workspace.js --serve",
     "build:docs": "wireit",
     "build:packages": "wireit",
     "watch": "wireit",
@@ -218,7 +219,8 @@
     "simple-git-hooks": "^2.12.1",
     "underscore": "^1.13.7",
     "vitest": "^3.0.9",
-    "wireit": "^0.14.11"
+    "wireit": "^0.14.11",
+    "ws": "^8.18.2"
   },
   "ciDependencies": {
     "axios": "^1.6.8",
diff --git a/packages/query/src/query.js b/packages/query/src/query.js
index 7c8be9756..f9a4c6c68 100755
--- a/packages/query/src/query.js
+++ b/packages/query/src/query.js
@@ -2,6 +2,7 @@ import {
   camelToKebab,
   each,
   findIndex,
+  get,
   inArray,
   isArray,
   isClient,
@@ -10,6 +11,7 @@ import {
   isObject,
   isPlainObject,
   isString,
+  keys,
 } from '@semantic-ui/utils';
 
 /*
@@ -46,7 +48,7 @@ export class Query {
     }
 
     // this is an existing query object
-    if(selector instanceof Query) {
+    if (selector instanceof Query) {
       elements = selector;
     }
 
@@ -99,7 +101,7 @@ export class Query {
       ? new Query(globalThis, this.options)
       : new Query(elements, { ...this.options, prevObject: this });
   }
-  
+
   end() {
     return this.prevObject || this;
   }
@@ -116,8 +118,10 @@ export class Query {
 
     // Add root if required
     if (includeRoot) {
-      if ((domSelector && root == selector) ||
-          (!domSelector && root.matches && root.matches(selector))) {
+      if (
+        (domSelector && root == selector)
+        || (!domSelector && root.matches && root.matches(selector))
+      ) {
         elements.add(root);
       }
     }
@@ -125,7 +129,8 @@ export class Query {
     // Query from root
     if (domSelector) {
       queriedRoot = true;
-    } else if (root.querySelectorAll) {
+    }
+    else if (root.querySelectorAll) {
       root.querySelectorAll(selector).forEach(el => elements.add(el));
       queriedRoot = true;
     }
@@ -150,7 +155,8 @@ export class Query {
           elements.add(selector);
           domFound = true;
         }
-      } else if (node.querySelectorAll) {
+      }
+      else if (node.querySelectorAll) {
         // Directly add to Set without intermediate array
         node.querySelectorAll(selector).forEach(el => elements.add(el));
       }
@@ -158,7 +164,7 @@ export class Query {
 
     const findElements = (node, selector, query) => {
       // Early termination condition for DOM selector search
-      if (domSelector && domFound) return;
+      if (domSelector && domFound) { return; }
 
       // If root element didn't support querySelectorAll, query each child node
       if (query === true) {
@@ -605,10 +611,10 @@ export class Query {
 
   getSlot(name) {
     return this.map((el) => {
-      if(el.tagName.toLowerCase() == 'slot' && (!name || el.name == name)) {
+      if (el.tagName.toLowerCase() == 'slot' && (!name || el.name == name)) {
         // called directly on a matching slot
         const nodes = el.assignedNodes({ flatten: true });
-        if(nodes) {
+        if (nodes) {
           return this.chain(nodes).html();
         }
       }
@@ -617,10 +623,11 @@ export class Query {
         const slotSelector = name ? `slot[name="${name}"]` : 'slot:not([name])';
         const slot = el.shadowRoot.querySelector(slotSelector);
         const nodes = slot.assignedNodes({ flatten: true });
-        if(nodes) {
+        if (nodes) {
           return this.chain(nodes).html();
         }
-      } else {
+      }
+      else {
         // No shadow DOM, fallback to direct DOM querying
         const slotSelector = name ? `[slot="${name}"]` : ':not([slot])';
         return this.chain(el).find(slotSelector).html();
@@ -629,18 +636,18 @@ export class Query {
   }
 
   setSlot(nameOrHTML, newHTML) {
-
     // Determine if we're dealing with a named slot or default slot based on arguments
     let name;
     if (newHTML) {
       name = nameOrHTML;
-    } else {
+    }
+    else {
       newHTML = nameOrHTML;
     }
 
     return this.each((el) => {
       // find host web component
-      if(el.tagName.toLowerCase() == 'slot') {
+      if (el.tagName.toLowerCase() == 'slot') {
         el = el.getRootNode().getRootNode()?.host;
       }
       const $el = this.chain(el);
@@ -653,7 +660,8 @@ export class Query {
           $slottedElement = this.chain(el).find(slotSelector);
         }
         $slottedElement.html(newHTML);
-      } else {
+      }
+      else {
         // Default slot updates the entire element content
         $el.html(newHTML);
       }
@@ -717,8 +725,7 @@ export class Query {
         || el instanceof HTMLSelectElement
         || el instanceof HTMLTextAreaElement
         // web components may store value
-        || customElements.get(el.tagName.toLowerCase())
-      ;
+        || customElements.get(el.tagName.toLowerCase());
     };
     if (newValue !== undefined) {
       // Set the value for each element
@@ -795,7 +802,7 @@ export class Query {
     return this.css(property, null, { includeComputed: true });
   }
 
-  cssVar(variable, value) {
+  cssVar(variable, value = null) {
     return this.css(`--${variable}`, value, { includeComputed: true });
   }
 
@@ -1035,29 +1042,69 @@ export class Query {
     return height.length > 1 ? height : height[0];
   }
 
-  // offsetParent does not return the true offset parent
-  // in cases where there is a parent node with a transform context
-  // so we need to get that manually where finding the true offset parent is essential
-  // for instance when calculating position
-  offsetParent({ calculate = true } = {}) {
-    return Array.from(this)
-      .map((el) => {
-        if (!calculate) {
-          return el.offsetParent;
+  // this is the element that clips current element
+  clippingParent() {
+    const parents = this.map((el) => {
+      let current = el.parentNode;
+      while (current) {
+        if (current instanceof Element) {
+          const style = window.getComputedStyle(current);
+          if (style.overflowX !== 'visible' || style.overflowY !== 'visible') {
+            return current;
+          }
         }
-        let $el, isPositioned, isTransformed, isBody;
-        let parentNode = el?.parentNode;
-        while (parentNode && !isPositioned && !isTransformed && !isBody) {
-          parentNode = parentNode?.parentNode;
-          if (parentNode) {
-            $el = $(parentNode);
-            isPositioned = $el.computedStyle('position') !== 'static';
-            isTransformed = $el.computedStyle('transform') !== 'none';
-            isBody = $el.is('body');
+        current = current.parentNode;
+      }
+      return document.documentElement;
+    });
+    return this.chain(parents);
+  }
+
+  // this is the parent element where top/left and offsetTop/left will be relative
+  containingParent({ calculate = true } = {}) {
+    const parents = this.map((el) => {
+
+      // return offset parent as reported by browser
+      if (!calculate) {
+        return el.offsetParent;
+      }
+
+      // fixed elements have no offset parent
+      if (window.getComputedStyle(el).position === 'fixed') {
+        return undefined;
+      }
+
+      let current = el.parentNode;
+      while (current) {
+        if (current instanceof Element) {
+          const style = window.getComputedStyle(current);
+          // transformed elements create new positioning context
+          if (style.position !== 'static') {
+            return current;
+          }
+          // filter creates new positioning context
+          if (style.filter !== 'none') {
+            return current;
+          }
+          // transformed elements create new positioning context
+          if (style.transform !== 'none') {
+            return current;
+          }
+          // also creates positioning context
+          if(['layout', 'paint', 'strict', 'content'].includes(style.contain)) {
+            return current;
+          }
+          // will change will trigger same context
+          // <https://issues.chromium.org/issues/41131675>
+          if (['filter', 'contain', 'transform'].includes(style.willChange)) {
+            return current;
           }
         }
-        return parentNode;
-      });
+        current = current.parentNode;
+      }
+      return document.body;
+    });
+    return this.chain(parents);
   }
 
   // alias
@@ -1084,11 +1131,67 @@ export class Query {
   }
 
   setting(setting, value) {
+    if (value === undefined) {
+      const settings = this.map(el => el[setting]);
+      return (settings.length == 1)
+        ? settings[0]
+        : settings;
+    }
     return this.each((el) => {
       el[setting] = value;
     });
   }
 
+  data(key, value) {
+
+    // Set data attribute
+    if (value !== undefined) {
+      return this.each(el => {
+        if (el.dataset) {
+          el.dataset[key] = value;
+        }
+      });
+    }
+
+    // Get single data attribute
+    if (key !== undefined) {
+      if (this.length === 0) {
+        return undefined;
+      }
+      const values = this.map(el => get(el, `dataset.${key}`));
+      return this.length === 1
+        ? values[0]
+        : values;
+    }
+
+    // Get all data attributes
+    if (this.length === 0) {
+      return undefined;
+    }
+    const allData = this.map(el => {
+      const data = {};
+      if (el.dataset) {
+        each(keys(el.dataset), k => {
+          data[k] = el.dataset[k];
+        });
+      }
+      return data;
+    });
+
+    // return array only if more than one el
+    return (this.length === 1)
+      ? allData[0]
+      : allData;
+  }
+
+  slice(start, end) {
+    if (this.length === 0) {
+      return this;
+    }
+    const slicedElements = Array.from(this).slice(start, end);
+    return this.chain(slicedElements);
+  }
+
   // special helper for SUI components
   component() {
     const components = this.map(el => el.component).filter(Boolean);
diff --git a/packages/query/test/browser/query.test.js b/packages/query/test/browser/query.test.js
index d8c569d67..e8c32b3f1 100644
--- a/packages/query/test/browser/query.test.js
+++ b/packages/query/test/browser/query.test.js
@@ -607,4 +607,278 @@ describe('query', () => {
       });
     });
   });
+
+  describe('clippingParent', () => {
+    beforeEach(() => {
+      document.body.innerHTML = '';
+    });
+
+    it('should find the clipping parent with overflow hidden', () => {
+      document.body.innerHTML = `
+        <div id="container" style="overflow: hidden; width: 200px; height: 200px;">
+          <div id="child">Child element</div>
+        </div>
+      `;
+
+      const $child = $('#child');
+      const $clippingParent = $child.clippingParent();
+
+      expect($clippingParent.length).toBe(1);
+      expect($clippingParent[0]).toBe(document.getElementById('container'));
+    });
+
+    it('should find the clipping parent with overflow scroll', () => {
+      document.body.innerHTML = `
+        <div id="outer">
+          <div id="scroller" style="overflow-y: scroll; height: 100px;">
+            <div id="inner">Inner content</div>
+          </div>
+        </div>
+      `;
+
+      const $inner = $('#inner');
+      const $clippingParent = $inner.clippingParent();
+
+      expect($clippingParent.length).toBe(1);
+      expect($clippingParent[0]).toBe(document.getElementById('scroller'));
+    });
+
+    it('should find the clipping parent with overflow auto', () => {
+      document.body.innerHTML = `
+        <div id="container" style="overflow: auto; width: 150px; height: 150px;">
+          <div id="content">Content</div>
+        </div>
+      `;
+
+      const $content = $('#content');
+      const $clippingParent = $content.clippingParent();
+
+      expect($clippingParent.length).toBe(1);
+      expect($clippingParent[0]).toBe(document.getElementById('container'));
+    });
+
+    it('should return document.documentElement when no clipping parent found', () => {
+      document.body.innerHTML = `
+        <div id="outer" style="overflow: visible;">
+          <div id="inner" style="overflow: visible;">
+            <div id="target">Target</div>
+          </div>
+        </div>
+      `;
+
+      const $target = $('#target');
+      const $clippingParent = $target.clippingParent();
+
+      expect($clippingParent.length).toBe(1);
+      expect($clippingParent[0]).toBe(document.documentElement);
+    });
+
+    it('should handle multiple elements', () => {
+      document.body.innerHTML = `
+        <div id="container1" style="overflow: hidden;">
+          <div class="item" id="item1">Item 1</div>
+        </div>
+        <div id="container2" style="overflow: scroll;">
+          <div class="item" id="item2">Item 2</div>
+        </div>
+      `;
+
+      const $items = $('.item');
+      const $clippingParents = $items.clippingParent();
+
+      expect($clippingParents.length).toBe(2);
+      expect($clippingParents[0]).toBe(document.getElementById('container1'));
+      expect($clippingParents[1]).toBe(document.getElementById('container2'));
+    });
+
+    it('should handle empty selection', () => {
+      const $empty = $('.nonexistent');
+      const $clippingParent = $empty.clippingParent();
+
+      expect($clippingParent.length).toBe(0);
+    });
+
+    it('should find nested clipping parents correctly', () => {
+      document.body.innerHTML = `
+        <div id="outer" style="overflow: hidden;">
+          <div id="middle" style="overflow: visible;">
+            <div id="inner" style="overflow: scroll;">
+              <div id="target">Target</div>
+            </div>
+          </div>
+        </div>
+      `;
+
+      const $target = $('#target');
+      const $clippingParent = $target.clippingParent();
+
+      // Should find the immediate clipping parent (inner), not the outer one
+      expect($clippingParent.length).toBe(1);
+      expect($clippingParent[0]).toBe(document.getElementById('inner'));
+    });
+  });
+
+  describe('containingParent', () => {
+    beforeEach(() => {
+      document.body.innerHTML = '';
+    });
+
+    it('should find containing parent with position relative', () => {
+      document.body.innerHTML = `
+        <div id="container" style="position: relative;">
+          <div id="child" style="position: absolute;">Child</div>
+        </div>
+      `;
+
+      const $child = $('#child');
+      const $containingParent = $child.containingParent();
+
+      expect($containingParent.length).toBe(1);
+      expect($containingParent[0]).toBe(document.getElementById('container'));
+    });
+
+    it('should find containing parent with transform', () => {
+      document.body.innerHTML = `
+        <div id="transformed" style="transform: translateX(10px);">
+          <div id="child">Child</div>
+        </div>
+      `;
+
+      const $child = $('#child');
+      const $containingParent = $child.containingParent();
+
+      expect($containingParent.length).toBe(1);
+      expect($containingParent[0]).toBe(document.getElementById('transformed'));
+    });
+
+    it('should find containing parent with filter', () => {
+      document.body.innerHTML = `
+        <div id="filtered" style="filter: blur(1px);">
+          <div id="child">Child</div>
+        </div>
+      `;
+
+      const $child = $('#child');
+      const $containingParent = $child.containingParent();
+
+      expect($containingParent.length).toBe(1);
+      expect($containingParent[0]).toBe(document.getElementById('filtered'));
+    });
+
+    it('should find containing parent with contain property', () => {
+      document.body.innerHTML = `
+        <div id="contained" style="contain: layout;">
+          <div id="child">Child</div>
+        </div>
+      `;
+
+      const $child = $('#child');
+      const $containingParent = $child.containingParent();
+
+      expect($containingParent.length).toBe(1);
+      expect($containingParent[0]).toBe(document.getElementById('contained'));
+    });
+
+    it('should find containing parent with will-change', () => {
+      document.body.innerHTML = `
+        <div id="willchange" style="will-change: transform;">
+          <div id="child">Child</div>
+        </div>
+      `;
+
+      const $child = $('#child');
+      const $containingParent = $child.containingParent();
+
+      expect($containingParent.length).toBe(1);
+      expect($containingParent[0]).toBe(document.getElementById('willchange'));
+    });
+
+    it('should return undefined for fixed position elements', () => {
+      document.body.innerHTML = `
+        <div id="container" style="position: relative;">
+          <div id="fixed" style="position: fixed;">Fixed element</div>
+        </div>
+      `;
+
+      const $fixed = $('#fixed');
+      const $containingParent = $fixed.containingParent();
+
+      expect($containingParent.length).toBe(1);
+      expect($containingParent[0]).toBe(undefined);
+    });
+
+    it('should return document.body when no containing parent found', () => {
+      document.body.innerHTML = `
+        <div id="outer" style="position: static;">
+          <div id="inner" style="position: static;">
+            <div id="target">Target</div>
+          </div>
+        </div>
+      `;
+
+      const $target = $('#target');
+      const $containingParent = $target.containingParent();
+
+      expect($containingParent.length).toBe(1);
+      expect($containingParent[0]).toBe(document.body);
+    });
+
+    it('should use browser offsetParent when calculate is false', () => {
+      document.body.innerHTML = `
+        <div id="container" style="position: relative;">
+          <div id="child">Child</div>
+        </div>
+      `;
+
+      const $child = $('#child');
+      const $containingParent = $child.containingParent({ calculate: false });
+
+      expect($containingParent.length).toBe(1);
+      expect($containingParent[0]).toBe(document.getElementById('child').offsetParent);
+    });
+
+    it('should handle multiple elements', () => {
+      document.body.innerHTML = `
+        <div id="container1" style="position: relative;">
+          <div class="item" id="item1">Item 1</div>
+        </div>
+        <div id="container2" style="transform: scale(1);">
+          <div class="item" id="item2">Item 2</div>
+        </div>
+      `;
+
+      const $items = $('.item');
+      const $containingParents = $items.containingParent();
+
+      expect($containingParents.length).toBe(2);
+      expect($containingParents[0]).toBe(document.getElementById('container1'));
+      expect($containingParents[1]).toBe(document.getElementById('container2'));
+    });
+
+    it('should handle empty selection', () => {
+      const $empty = $('.nonexistent');
+      const $containingParent = $empty.containingParent();
+
+      expect($containingParent.length).toBe(0);
+    });
+
+    it('should find nearest containing parent in nested contexts', () => {
+      document.body.innerHTML = `
+        <div id="outer" style="position: relative;">
+          <div id="middle" style="position: static;">
+            <div id="inner" style="transform: translateY(5px);">
+              <div id="target">Target</div>
+            </div>
+          </div>
+        </div>
+      `;
+
+      const $target = $('#target');
+      const $containingParent = $target.containingParent();
+
+      // Should find the immediate containing parent (inner), not the outer one
+      expect($containingParent.length).toBe(1);
+      expect($containingParent[0]).toBe(document.getElementById('inner'));
+    });
+  });
 });
diff --git a/packages/query/test/dom/query.test.js b/packages/query/test/dom/query.test.js
index 29ed3ca12..ac547338e 100644
--- a/packages/query/test/dom/query.test.js
+++ b/packages/query/test/dom/query.test.js
@@ -1727,6 +1727,121 @@ describe('query', () => {
     });
   });
 
+  describe('data', () => {
+    beforeEach(() => {
+      document.body.innerHTML = '';
+    });
+
+    it('should set and get data attributes', () => {
+      const div = document.createElement('div');
+      document.body.appendChild(div);
+      
+      $('div').data('test', 'value');
+      expect($('div').data('test')).toBe('value');
+      expect(div.dataset.test).toBe('value');
+    });
+
+    it('should get all data attributes when no key provided', () => {
+      const div = document.createElement('div');
+      div.dataset.foo = 'bar';
+      div.dataset.baz = 'qux';
+      document.body.appendChild(div);
+      
+      const data = $('div').data();
+      expect(data).toEqual({ foo: 'bar', baz: 'qux' });
+    });
+
+    it('should return undefined for non-existent data attribute', () => {
+      const div = document.createElement('div');
+      document.body.appendChild(div);
+      
+      expect($('div').data('nonexistent')).toBe(undefined);
+    });
+
+    it('should return undefined when getting data on empty selection', () => {
+      expect($('.nonexistent').data('test')).toBe(undefined);
+      expect($('.nonexistent').data()).toBe(undefined);
+    });
+
+    it('should set data attributes on multiple elements', () => {
+      const div1 = document.createElement('div');
+      const div2 = document.createElement('div');
+      document.body.appendChild(div1);
+      document.body.appendChild(div2);
+      
+      $('div').data('test', 'value');
+      expect(div1.dataset.test).toBe('value');
+      expect(div2.dataset.test).toBe('value');
+    });
+
+    it('should get data attribute from single element', () => {
+      const div = document.createElement('div');
+      div.dataset.test = 'value';
+      document.body.appendChild(div);
+      
+      expect($('div').data('test')).toBe('value');
+    });
+
+    it('should get data attributes from multiple elements as array', () => {
+      const div1 = document.createElement('div');
+      const div2 = document.createElement('div');
+      div1.dataset.test = 'value1';
+      div2.dataset.test = 'value2';
+      document.body.appendChild(div1);
+      document.body.appendChild(div2);
+      
+      expect($('div').data('test')).toEqual(['value1', 'value2']);
+    });
+
+    it('should get all data attributes from single element as object', () => {
+      const div = document.createElement('div');
+      div.dataset.foo = 'bar';
+      div.dataset.baz = 'qux';
+      document.body.appendChild(div);
+      
+      expect($('div').data()).toEqual({ foo: 'bar', baz: 'qux' });
+    });
+
+    it('should get all data attributes from multiple elements as array of objects', () => {
+      const div1 = document.createElement('div');
+      const div2 = document.createElement('div');
+      div1.dataset.foo = 'bar1';
+      div1.dataset.baz = 'qux1';
+      div2.dataset.foo = 'bar2';
+      div2.dataset.test = 'value2';
+      document.body.appendChild(div1);
+      document.body.appendChild(div2);
+      
+      const result = $('div').data();
+      expect(result).toEqual([
+        { foo: 'bar1', baz: 'qux1' },
+        { foo: 'bar2', test: 'value2' }
+      ]);
+    });
+
+    it('should handle elements without dataset', () => {
+      const div = document.createElement('div');
+      // Remove dataset to simulate older browsers or non-HTML elements
+      Object.defineProperty(div, 'dataset', { value: null });
+      document.body.appendChild(div);
+      
+      expect($('div').data()).toEqual({});
+      expect($('div').data('test')).toBe(undefined);
+      
+      // Setting should not throw
+      expect(() => $('div').data('test', 'value')).not.toThrow();
+    });
+
+    it('should return the Query instance when setting data', () => {
+      const div = document.createElement('div');
+      document.body.appendChild(div);
+      
+      const result = $('div').data('test', 'value');
+      expect(result).toBeInstanceOf(Query);
+      expect(result[0]).toBe(div);
+    });
+  });
+
   describe('end', () => {
     beforeEach(() => {
       document.body.innerHTML = '';
@@ -1865,4 +1980,143 @@ describe('query', () => {
       expect(result[0]).toBe(outer);
     });
   });
+
+  describe('slice', () => {
+    beforeEach(() => {
+      document.body.innerHTML = '';
+    });
+
+    it('should slice elements from the collection', () => {
+      const div1 = document.createElement('div');
+      const div2 = document.createElement('div');
+      const div3 = document.createElement('div');
+      const div4 = document.createElement('div');
+      
+      div1.className = 'item';
+      div2.className = 'item';
+      div3.className = 'item';
+      div4.className = 'item';
+      
+      document.body.appendChild(div1);
+      document.body.appendChild(div2);
+      document.body.appendChild(div3);
+      document.body.appendChild(div4);
+
+      const $items = $('.item');
+      const $sliced = $items.slice(1, 3);
+
+      expect($sliced.length).toBe(2);
+      expect($sliced[0]).toBe(div2);
+      expect($sliced[1]).toBe(div3);
+    });
+
+    it('should slice with only start parameter', () => {
+      const div1 = document.createElement('div');
+      const div2 = document.createElement('div');
+      const div3 = document.createElement('div');
+      
+      div1.className = 'item';
+      div2.className = 'item';
+      div3.className = 'item';
+      
+      document.body.appendChild(div1);
+      document.body.appendChild(div2);
+      document.body.appendChild(div3);
+
+      const $items = $('.item');
+      const $sliced = $items.slice(1);
+
+      expect($sliced.length).toBe(2);
+      expect($sliced[0]).toBe(div2);
+      expect($sliced[1]).toBe(div3);
+    });
+
+    it('should handle negative indices', () => {
+      const div1 = document.createElement('div');
+      const div2 = document.createElement('div');
+      const div3 = document.createElement('div');
+      
+      div1.className = 'item';
+      div2.className = 'item';
+      div3.className = 'item';
+      
+      document.body.appendChild(div1);
+      document.body.appendChild(div2);
+      document.body.appendChild(div3);
+
+      const $items = $('.item');
+      const $sliced = $items.slice(-2);
+
+      expect($sliced.length).toBe(2);
+      expect($sliced[0]).toBe(div2);
+      expect($sliced[1]).toBe(div3);
+    });
+
+    it('should return empty collection when start is beyond collection length', () => {
+      const div1 = document.createElement('div');
+      div1.className = 'item';
+      document.body.appendChild(div1);
+
+      const $items = $('.item');
+      const $sliced = $items.slice(5);
+
+      expect($sliced.length).toBe(0);
+      expect($sliced).toBeInstanceOf(Query);
+    });
+
+    it('should return same instance when called on empty collection', () => {
+      const $empty = $('.nonexistent');
+      const $sliced = $empty.slice(0, 2);
+
+      expect($sliced).toBe($empty);
+      expect($sliced.length).toBe(0);
+    });
+
+    it('should return Query instance for chaining', () => {
+      const div1 = document.createElement('div');
+      const div2 = document.createElement('div');
+      
+      div1.className = 'item';
+      div2.className = 'item';
+      
+      document.body.appendChild(div1);
+      document.body.appendChild(div2);
+
+      const $result = $('.item').slice(0, 1).addClass('sliced');
+
+      expect($result).toBeInstanceOf(Query);
+      expect($result.length).toBe(1);
+      expect(div1.classList.contains('sliced')).toBe(true);
+      expect(div2.classList.contains('sliced')).toBe(false);
+    });
+
+    it('should work with single element', () => {
+      const div = document.createElement('div');
+      div.className = 'item';
+      document.body.appendChild(div);
+
+      const $items = $('.item');
+      const $sliced = $items.slice(0, 1);
+
+      expect($sliced.length).toBe(1);
+      expect($sliced[0]).toBe(div);
+    });
+
+    it('should handle zero slice', () => {
+      const div1 = document.createElement('div');
+      const div2 = document.createElement('div');
+      
+      div1.className = 'item';
+      div2.className = 'item';
+      
+      document.body.appendChild(div1);
+      document.body.appendChild(div2);
+
+      const $items = $('.item');
+      const $sliced = $items.slice(1, 1);
+
+      expect($sliced.length).toBe(0);
+      expect($sliced).toBeInstanceOf(Query);
+    });
+  });
 });
diff --git a/packages/query/types/query.d.ts b/packages/query/types/query.d.ts
index fee48e747..a82648765 100644
--- a/packages/query/types/query.d.ts
+++ b/packages/query/types/query.d.ts
@@ -640,6 +640,15 @@ export class Query {
    */
   reverse(): Query;
 
+  /**
+   * Returns a shallow copy of a portion of the elements into a new Query object.
+   * @see https://next.semantic-ui.com/api/query/dom-manipulation#slice
+   * @param start - The beginning index of the specified portion of the collection.
+   * @param end - The end index of the specified portion of the collection (exclusive).
+   * @returns A new Query instance containing the sliced elements.
+   */
+  slice(start?: number, end?: number): Query;
+
   /**
    * Inserts content at a specified position relative to a target element.
    * @see https://next.semantic-ui.com/api/query/internal#insertcontent
@@ -707,13 +716,20 @@ export class Query {
   naturalHeight(): number | number[];
 
   /**
-   * Gets the offset parent of each element in the current set, optionally calculating it accurately
-   * by considering transformed parent.
-   * @see https://next.semantic-ui.com/api/query/size-and-position#offsetParent
-   * @param options.calculate - Whether to calculate offset parent taking transform into account.
-   * @returns An array of the offset parent elements.
+   * Gets the clipping parent (overflow container) of each element in the current set.
+   * @see https://next.semantic-ui.com/api/query/dimensions#clippingparent
+   * @returns A new Query instance containing the clipping parent elements.
    */
-  offsetParent(options?: { calculate?: boolean; }): (HTMLElement | null)[];
+  clippingParent(): Query;
+
+  /**
+   * Gets the containing parent (positioning context) of each element in the current set, optionally calculating it accurately
+   * by considering transform, filter, and other properties that create new positioning contexts.
+   * @see https://next.semantic-ui.com/api/query/dimensions#containingparent
+   * @param options.calculate - Whether to calculate containing parent taking modern CSS properties into account.
+   * @returns A new Query instance containing the containing parent elements.
+   */
+  containingParent(options?: { calculate?: boolean; }): Query;
 
   /**
    * Gets the number of elements in the current set.  Alias for `length`.
@@ -759,6 +775,26 @@ export class Query {
    */
   component(): any;
 
+  /**
+   * Gets or sets data attributes on elements in the current set.
+   * @see https://next.semantic-ui.com/api/query/data#data
+   * @param key - The data attribute key.
+   * @param value - The value to set.
+   * @returns If setting, the Query instance for chaining. If getting, the value(s).
+   */
+  data(key: string, value: string): this;
+  /**
+   * Gets a data attribute from elements in the current set.
+   * @param key - The data attribute key to retrieve.
+   * @returns The value from the first element, or an array of values from all elements.
+   */
+  data(key: string): string | string[] | undefined;
+  /**
+   * Gets all data attributes from elements in the current set.
+   * @returns An object of data attributes from the first element, or an array of objects from all elements.
+   */
+  data(): PlainObject<string> | PlainObject<string>[] | undefined;
+
   /**
    * Gets the data context (if any) associated with the *first* element in the current set.
    * @see https://next.semantic-ui.com/api/query/components#datacontext
diff --git a/packages/templating/src/compiler/string-scanner.js b/packages/templating/src/compiler/string-scanner.js
index 0d46dc955..e1b361c15 100644
--- a/packages/templating/src/compiler/string-scanner.js
+++ b/packages/templating/src/compiler/string-scanner.js
@@ -110,8 +110,9 @@ export class StringScanner {
 
     // Step 1: Search backwards to confirm we're inside a tag.
     while (i >= 0) {
-      if (this.input[i] === '>') { break; // Stop if we find the end of a previous tag
-       }
+      if (this.input[i] === '>') {
+        break; // Stop if we find the end of a previous tag
+      }
       if (this.input[i] === '<') {
         insideTag = true; // Confirm we're inside a tag
         tagPos = i; // Save the position of the tag