jj 3.0.0-rc.5 → 3.0.0-rc.7

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jj",
-    "version": "3.0.0-rc.5",
+    "version": "3.0.0-rc.7",
     "description": "A minimal DOM manipulation library with web components",
     "keywords": [
         "javascript",

package/skills/SKILL.md

@@ -7,6 +7,42 @@ description: Expert guide for the JJ DOM manipulation library. Load this skill w
 
 JJ is a minimal, zero-dependency TypeScript library that wraps browser DOM interfaces in fluent, type-safe classes. It complements native browser APIs rather than replacing them.
 
+## Translation Checklist
+
+When converting native DOM code, framework code, or vague UI requests into JJ, default to this order of thought:
+
+- Start from wrappers, not native nodes: `JJD.from(document)`, `JJHE.create()`, `JJHE.tree()`, `JJET.from(window)`, `getShadow(true)`.
+- Keep values wrapped and chain operations; use `.ref` only for native APIs JJ does not provide.
+- Use `JJHE.tree` with a local `h` alias for multi-node or nested UI.
+- Use `setChild()`/`setChildren()` to replace content and `addChildMap()`/`setChildMap()` for array rendering.
+- Query with `find()`/`findAll()`/`closest()` instead of native `querySelector*` when JJ already covers the case.
+- For form-like value elements (`input`, `select`, `textarea`, `progress`, etc.), prefer `getValue()` / `setValue(...)` over `.ref.value`.
+- Use `setText()` for user content and treat `setHTML(..., true)` as a trusted-content escape hatch.
+- For repeated child interactions, prefer one delegated listener on a stable parent over one listener per child.
+- Choose shadow DOM for self-contained widgets and light DOM for page-level content that should inherit global styles.
+- For components, keep fetched templates/styles at module scope, attach shadow root in the constructor, initialize once, then update targeted nodes instead of rebuilding the whole tree.
+- Prefer `'open'` shadow roots unless the user explicitly needs `'closed'`; open mode is easier to test and debug.
+- Use plain JS state plus targeted wrapper updates by default; do not invent a virtual DOM style rerender loop unless the user explicitly wants one.
+
+## Naming Conventions
+
+In this repository, prefix variables that hold JJ wrapper instances with `jj`.
+
+```typescript
+const jjDoc = JJD.from(document)
+const jjFruits = jjDoc.find('#fruits', true)
+const jjSubmitBtn = jjDoc.find('button#submit', true)
+const jjDialog = JJHE.create('dialog')
+```
+
+Naming defaults:
+
+- Use `jj*` for JJ wrappers, including private fields: `#jjHost` for `JJHE.from(this)` (the wrapped host element) and `#jjShadow` for `this.#jjHost.getShadow()` (the wrapped shadow root).
+- Do not use `jj*` for plain data like `fruits`, `title`, `isOpen`, or `userName`.
+- Do not use `jj*` for native DOM values; prefer names like `formEl`, `shadowRoot`, `inputRef`, or `styleSheet`.
+- For promises, use normal names with `Promise`, like `templatePromise` or `stylePromise`.
+- `h` is the main intentional exception: use it as the local alias for `JJHE.tree`.
+
 ## Wrapper Hierarchy
 
 Each JJ wrapper exposes the native node via `.ref`.
@@ -29,12 +65,12 @@ Each JJ wrapper exposes the native node via `.ref`.
 
 ```typescript
 // ✅ CORRECT — factory methods infer the precise generic type
-const div = JJHE.create('div') // JJHE<HTMLDivElement>
-const input = JJHE.create('input') // JJHE<HTMLInputElement>
-const svg = JJSE.create('svg') // JJSE<SVGSVGElement>
-const math = JJME.create('math') // JJME<MathMLElement>
-const frag = JJDF.create() // JJDF
-const btn = JJHE.fromId('my-btn') // JJHE<HTMLButtonElement>
+const jjDiv = JJHE.create('div') // JJHE<HTMLDivElement>
+const jjInput = JJHE.create('input') // JJHE<HTMLInputElement>
+const jjSvg = JJSE.create('svg') // JJSE<SVGSVGElement>
+const jjMath = JJME.create('math') // JJME<MathMLElement>
+const jjFrag = JJDF.create() // JJDF
+const jjBtn = JJHE.fromId('my-btn') // JJHE<HTMLButtonElement>
 
 // ❌ WRONG
 JJHE.create('svg') // throws — use JJSE.create('svg')
@@ -46,7 +82,7 @@ new JJHE(element) // don't call constructors directly
 All mutating methods return `this`. Chain as much as possible; access `.ref` only when a wrapper method does not exist.
 
 ```typescript
-const btn = JJHE.create('button')
+const jjBtn = JJHE.create('button')
     .addClass('btn', 'primary')
     .setText('Save')
     .setAttr('type', 'submit')
@@ -54,98 +90,153 @@ const btn = JJHE.create('button')
     .on('click', handleSave)
 ```
 
+## Tutorial Defaults — Prefer JJ Idioms Over Native DOM Steps
+
+When translating browser DOM code into JJ, do not mechanically keep native patterns like repeated `appendChild`, `querySelector`, or unwrap/re-wrap flows. Prefer the JJ equivalent that keeps work inside wrappers.
+
+```typescript
+// ✅ preferred: build a subtree once
+const h = JJHE.tree
+
+latestChatResponse.addChild(
+    h('section', null, h('h2', null, 'User'), h('div', null, userPrompt), h('h2', null, 'Assistant'), assistantMessage),
+)
+
+// ✅ also fine for flat mapped children
+const jjList = JJHE.create('ul').addChildMap(fruits, (fruit) => h('li', null, fruit))
+
+// ❌ avoid native-style wrapper escape hatches when JJ already covers it
+latestChatResponse.ref.appendChild(JJHE.create('h2').setText('User').ref)
+latestChatResponse.ref.appendChild(JJHE.create('div').setText(userPrompt).ref)
+latestChatResponse.ref.appendChild(JJHE.create('h2').setText('Assistant').ref)
+latestChatResponse.ref.appendChild(assistantMessage.ref)
+```
+
+Default heuristics from the tutorial:
+
+- Use `JJHE.tree` with a local `h` alias when creating multiple siblings or any nested subtree.
+- Use `create()` for one-off elements; switch to `tree()` as soon as structure becomes non-trivial.
+- Prefer `setChild()` or `setChildren()` when replacing content, not `.empty().addChild()`.
+- Prefer `addChildMap()` or `setChildMap()` when rendering from arrays.
+- Keep values wrapped. Reach for `.ref` only for native APIs JJ does not expose.
+- Use JJ verb families consistently: `set*` replaces, `add*` appends, `pre*` prepends, `rm*` removes, `sw*` toggles.
+
 ## Document Queries
 
 Wrap `document` with `JJD.from(document)` before querying.
 
 ```typescript
-const doc = JJD.from(document)
-const app = doc.find('#app', true) // throws when absent
-const card = doc.find('.card') // null when absent
-const items = doc.findAll('.item') // always an array
+const jjDoc = JJD.from(document)
+const jjApp = jjDoc.find('#app', true) // throws when absent
+const jjCard = jjDoc.find('.card') // null when absent
+const jjItems = jjDoc.findAll('.item') // always an array
 
 // Inside a custom element's shadow root
-const btn = this.getShadow(true).find('#submit')
+const jjBtn = this.getShadow(true).find('#submit')
 ```
 
+Querying defaults from the tutorial:
+
+- Start from a wrapped container like `JJD.from(document)` or a `JJSR` shadow root.
+- Prefer `find(selector, true)` when absence is a bug; it fails earlier and more clearly than a later null access.
+- Prefer narrower selectors that encode expectations, like `button#submit`, instead of broad lookups plus manual type checks.
+- Use `findAll()` for arrays of wrappers and keep operating on wrappers instead of unwrapping to native elements.
+- Do not use `.ref.querySelector(...)` or `.ref.querySelectorAll(...)` when `find()` or `findAll()` already covers the case.
+- Use `.closest()` on wrappers for event delegation and ancestor lookup.
+- Use `JJHE.fromId('submit-btn')` for direct ID lookup when you already know the target is an HTML element.
+
 ## Attributes, Classes, Styles
 
 ```typescript
 // Attribute — singular
-el.setAttr('role', 'button')
-el.getAttr('role')
-el.rmAttr('hidden')
-el.swAttr('disabled', !isReady) // sets disabled="" or removes it
+jjEl.setAttr('role', 'button')
+jjEl.getAttr('role')
+jjEl.rmAttr('hidden')
+jjEl.swAttr('readonly') // auto: flips current state of the "readonly" attribute
+jjEl.swAttr('disabled', !isReady) // sets disabled="" or removes it
 
 // Attribute — batch (null/undefined skipped)
-el.setAttrs({ type: 'text', placeholder: 'Search…' })
+jjEl.setAttrs({ type: 'text', placeholder: 'Search…' })
 
 // Classes
-el.addClass('active')
-el.addClasses(['chip', 'selected'])
-el.rmClass('disabled')
-el.rmClasses(['pending', 'loading'])
-el.swClass('expanded', isExpanded) // explicit: adds when truthy, removes when falsy
-el.swClass('is-active') // auto: flips current state (adds if absent, removes if present)
-el.swAttr('disabled', !isReady) // explicit: sets disabled="" or removes it
-el.swAttr('readonly') // auto: flips current state
-el.setClasses({ active: isActive, disabled: !isReady })
-el.setClass('card card--featured') // replaces entire className
+jjEl.addClass('active')
+// Multiple classes via varargs
+jjEl.addClass('active', 'selected')
+jjEl.rmClass('active', 'loading')
+// Multiple classes via array
+jjEl.addClasses(['chip', 'selected'])
+jjEl.rmClasses(['pending', 'loading'])
+// Explicit mode: truthy adds, falsy removes
+jjEl.swClass('expanded', isExpanded)
+// Auto mode: flips current state
+jjEl.swClass('is-active')
+
+// Batch conditional class updates
+jjEl.setClasses({ active: isActive, disabled: !isReady })
+// Replace the entire className
+jjEl.setClass('card card--featured')
 
 // Dataset
-el.getDataAttr('userId')
-el.hasDataAttr('userId')
-el.setDataAttr('userId', '42')
-el.setDataAttrs({ role: 'admin', team: 'ui' })
-el.rmDataAttr('userId')
-el.rmDataAttrs(['role', 'team'])
+jjEl.getDataAttr('userId')
+jjEl.hasDataAttr('userId')
+jjEl.setDataAttr('userId', '42')
+jjEl.setDataAttrs({ role: 'admin', team: 'ui' }) // batch set
+jjEl.rmDataAttr('userId')
+jjEl.rmDataAttr('role', 'team') // batch remove, varargs syntax
+jjEl.rmDataAttrs(['role', 'team']) // batch remove, array syntax
 
 // ARIA
-el.getAriaAttr('hidden')
-el.hasAriaAttr('hidden')
-el.setAriaAttr('hidden', 'true')
-el.setAriaAttrs({ label: 'Dialog', modal: 'true' })
-el.rmAriaAttr('hidden')
+jjEl.getAriaAttr('hidden')
+jjEl.hasAriaAttr('hidden')
+jjEl.setAriaAttr('hidden', 'true')
+jjEl.setAriaAttrs({ label: 'Dialog', modal: 'true' })
+jjEl.rmAriaAttr('hidden')
 
 // ARIA is not presence-based like HTML boolean attributes
 // Use explicit string states instead of swAttr()
-el.setAriaAttr('disabled', 'true')
+jjEl.setAriaAttr('disabled', 'true')
 
 // Inline styles
-el.setStyle('color', 'var(--color-brand)')
-el.setStyles({ color: 'red', padding: '8px', border: null })
-el.rmStyle('color', 'padding')
+jjEl.setStyle('color', 'var(--color-brand)')
+jjEl.setStyles({ color: 'red', padding: '8px', border: null })
+jjEl.rmStyle('color', 'padding')
+
+// Value helpers (prefer over .ref.value)
+jjEl.getValue()
+jjEl.setValue('next')
 ```
 
+Use `.ref.value` only when a JJ value helper is unavailable for your exact use case.
+
 ## Security — HTML Writes
 
 Prefer `.setText()` for any user-supplied content. `.setHTML()` requires an explicit `true` flag when the string is non-empty.
 
 ```typescript
-el.setText(userInput) // ✅ always safe
-el.setHTML('<p>Trusted markup</p>', true) // ✅ explicit opt-in
-el.setHTML('') // ✅ clearing is allowed without flag
-el.setHTML('<p>content</p>') // ❌ THROWS — missing unsafe flag
-el.ref.innerHTML = '…' // ❌ bypasses guard — avoid
+jjEl.setText(userInput) // ✅ always safe
+jjEl.setHTML('<p>Trusted markup</p>', true) // ✅ explicit opt-in
+jjEl.setHTML('') // ✅ clearing is allowed without flag
+jjEl.setHTML('<p>content</p>') // ❌ THROWS — missing unsafe flag
+jjEl.ref.innerHTML = '…' // ❌ bypasses guard — avoid
 ```
 
 ## Events
 
 ```typescript
 // Native events
-el.on('click', handler)
-el.off('click', handler)
-el.trigger('click')
+jjEl.on('click', handler)
+jjEl.off('click', handler)
+jjEl.triggerEvent('click')
 
 // Explicit event objects (equivalent to JJ helpers below)
-el.trigger(new Event('click', { bubbles: true, composed: true }))
-el.trigger(new CustomEvent('todo-toggle', { detail: { id: 1, done: true }, bubbles: true, composed: true }))
+jjEl.trigger(new Event('click', { bubbles: true, composed: true }))
+jjEl.trigger(new CustomEvent('todo-toggle', { detail: { id: 1, done: true }, bubbles: true, composed: true }))
 
 // Custom events — JJ defaults: bubbles: true, composed: true
 this.dispatchEvent(new CustomEvent('todo-toggle', { detail: { id: 1, done: true }, bubbles: true, composed: true }))
 
 // Fluent dispatch (same defaults)
-el.triggerEvent('click') // equivalent to trigger(new Event('click', { bubbles: true, composed: true }))
+jjEl.triggerEvent('click') // equivalent to trigger(new Event('click', { bubbles: true, composed: true }))
 JJHE.from(this).triggerCustomEvent('todo-toggle', { id: 1, done: true })
 // equivalent to trigger(new CustomEvent('todo-toggle', { detail: { id: 1, done: true }, bubbles: true, composed: true }))
 
@@ -153,10 +244,41 @@ JJHE.from(this).triggerCustomEvent('todo-toggle', { id: 1, done: true })
 new CustomEvent('panel-ready', { bubbles: false, composed: false })
 ```
 
+Event defaults from the tutorial:
+
+- Prefer `.on()` and `.off()` on wrappers over native `addEventListener`/`removeEventListener` when already working with JJ values.
+- Prefer `.triggerEvent()` and `.triggerCustomEvent()` for common JJ event dispatch; they default to `bubbles: true` and `composed: true`.
+- Use `triggerCustomEvent(name, detail)` for component-to-parent communication instead of ad hoc callback plumbing.
+- Use `bubbles: false` and `composed: false` only for intentionally internal events.
+- Keep event code close to the wrapper it affects so later DOM updates stay targeted and local.
+
+Guide defaults for event-heavy UI:
+
+- Prefer event delegation on a common parent for repeated child actions instead of binding one listener per item.
+- Use `.closest()` to recover the intended delegated target from `event.target`.
+- When you need JJ's wrapper-bound `this` inside a listener, use `function` syntax, not an arrow.
+- Native UI events like `click`, `input`, and `change` already cross shadow boundaries; custom events do not unless `composed: true`.
+
+```typescript
+list.on('click', function (event) {
+    const jjItem = JJHE.from(event.target as Node).closest('[data-item-id]')
+    if (!jjItem) return
+    this.addClass('handled')
+    jjItem.addClass('active')
+})
+```
+
 ## Custom Elements — Complete Pattern
 
 Fetch template and style at **module scope** — loaded once, shared across all instances.
 
+Guide defaults for component shape:
+
+- Use shadow DOM for self-contained widgets and design-system components; use light DOM for sections that should inherit page styling and normal document flow.
+- Prefer `'open'` shadow mode unless stricter encapsulation is a hard requirement.
+- `attributeChangedCallback()` can run before `connectedCallback()` for parsed attributes, so setters and render paths must tolerate pre-mount state.
+- Use `disconnectedCallback()` only to clean up external side effects like document listeners, timers, observers, or subscriptions; do not tear down the shadow root just because the element was detached.
+
 ```typescript
 import { attr2prop, defineComponent, fetchStyle, fetchTemplate, JJHE } from 'jj'
 
@@ -169,12 +291,12 @@ export class MyCard extends HTMLElement {
 
     #userName = ''
     #count = 0
-    #root = null // JJSR wrapper; attached in constructor
+    #jjShadow = null // JJSR wrapper; attached in constructor
     #isInitialized = false
 
     constructor() {
         super()
-        this.#root = JJHE.from(this).setShadow('open').getShadow(true)
+        this.#jjShadow = JJHE.from(this).setShadow('open').getShadow(true)
     }
 
     attributeChangedCallback(name, oldValue, newValue) {
@@ -200,16 +322,16 @@ export class MyCard extends HTMLElement {
 
     async connectedCallback() {
         if (!this.#isInitialized) {
-            this.#root.init(await templatePromise, await stylePromise)
+            this.#jjShadow.init(await templatePromise, await stylePromise)
             this.#isInitialized = true
         }
         this.#render()
     }
 
     #render() {
-        if (!this.#root) return // guard for attribute changes before mount
-        this.#root.find('[data-role="name"]')?.setText(this.#userName)
-        this.#root.find('[data-role="count"]')?.setText(String(this.#count))
+        if (!this.#jjShadow) return // guard for attribute changes before mount
+        this.#jjShadow.find('[data-role="name"]')?.setText(this.#userName)
+        this.#jjShadow.find('[data-role="count"]')?.setText(String(this.#count))
     }
 }
 
@@ -219,6 +341,28 @@ await MyCard.defined
 await Promise.all([MyCard.defined, OtherCard.defined])
 ```
 
+Template defaults from the tutorial:
+
+- Prefer fetched `.html` templates for large static markup.
+- Prefer `<template>` elements for reusable DOM snippets already present in the page.
+- Prefer `JJHE.tree()` or `JJHE.create()` when you need live wrapper references for later updates.
+- Keep template promises at module scope; for lazy loading, initialize them inside `connectedCallback()` with an `if (!templatePromise)` guard.
+- Use one stable wrapper per component: `#jjHost` with `JJHE.from(this)` for light DOM, or `#jjShadow` with `JJHE.from(this).setShadow(...).getShadow(true)` for shadow DOM.
+- Initialize template content once, then update specific nodes with `find(...).setText(...)` or other targeted wrapper operations.
+
+Guide defaults for attributes and queries:
+
+- Always coerce attribute-backed values in setters because HTML attributes arrive as strings.
+- Query inside shadow DOM from the `JJSR` wrapper, never from `document`.
+- Use specific selectors like `button#submit` or `[data-role="title"]` so the selector carries intent.
+
+State defaults from the tutorial:
+
+- Prefer plain objects or classes for state and update the exact affected wrappers in event handlers or setters.
+- Prefer targeted updates like `value.setText(String(state.count))` over rebuilding an entire subtree for a small change.
+- Use getters/setters or small helper methods when they make state transitions clearer, not because JJ requires a framework-style abstraction.
+- Reach for external state libraries only when the application actually needs cross-cutting coordination beyond local JS state.
+
 `defineComponent()` returns `Promise<boolean>`:
 
 - `false` — newly defined by this call
@@ -244,29 +388,36 @@ const card = h(
 
 ```typescript
 // Clear children — internally uses replaceChildren()
-el.empty()
+jjEl.empty()
 
 // Replace all children in one call (prefer over .empty().addChild())
-el.setChild(newChild)
-el.setChildren([childA, childB])
-el.setChildMap(items, (item) => JJHE.tree('li', null, item.label))
-el.setTemplate(templateElement)
+jjEl.setChild(newChild)
+jjEl.setChildren([childA, childB])
+jjEl.setChildMap(items, (item) => JJHE.tree('li', null, item.label))
+jjEl.setTemplate(templateElement)
 
 // Append
-el.addChild(child)
-el.addChildMap(items, (item) => JJHE.tree('li', null, item.label))
-el.addTemplate(await templatePromise) // clones before appending
+jjEl.addChild(child)
+jjEl.addChildMap(items, (item) => JJHE.tree('li', null, item.label))
+jjEl.addTemplate(await templatePromise) // clones before appending
 ```
 
 `addChild` / `preChild` / `setChild` and map variants ignore `null`/`undefined`; all other non-node values are coerced to Text nodes.
 
+Guide defaults for template and fragment usage:
+
+- `addTemplate()` and `setTemplate()` always clone the input before appending; reuse the same template value safely.
+- Prefer `setTemplate()` over `empty().addTemplate()` when replacing all content.
+- Prefer `addChildMap()` or `setChildMap()` over manually building a fragment when rendering arrays.
+- Use `JJDF.create()` when you need to assemble multiple sibling nodes before one insertion.
+
 ## Node Traversal
 
 ```typescript
-const parent = el.getParent() // wrapped parent or null (detached)
-const children = el.getChildren() // wrapped child array (always an array)
-el.rm() // detach from parent (no-op if already detached)
-const ancestor = el.closest('[data-section]') // null if not found
+const parent = jjEl.getParent() // wrapped parent or null (detached)
+const children = jjEl.getChildren() // wrapped child array (always an array)
+jjEl.rm() // detach from parent (no-op if already detached)
+const ancestor = jjEl.closest('[data-section]') // null if not found
 ```
 
 ## Resource Loaders
@@ -299,6 +450,12 @@ document.adoptedStyleSheets = [sheet]
 const fragment = await fetchTemplate(import.meta.resolve('./dialog.html'))
 ```
 
+Guide defaults for browser-native loading hints:
+
+- Use native `<link>` hints built with `JJHE.tree` and appended to `head` for `preload`, `prefetch`, and `modulepreload`.
+- Keep the `as` value explicit for `preload` instead of inferring it from file extensions.
+- Use `preload` for current-page needs, `prefetch` for probable future navigation, and `modulepreload` for module graphs you want fetched early.
+
 ## String Casing
 
 String case-conversion helpers are internal implementation details.
@@ -308,10 +465,11 @@ Use higher-level public APIs like `attr2prop` and `defineComponent` instead of i
 
 1. **`.ts` extension in imports** — TypeScript source must use `.js` (`import { X } from './X.js'`).
 2. **`JJHE.create('svg')`** — throws; use `JJSE.create('svg')`.
-3. **`el.setHTML(html)` without `true`** — throws when html is non-empty.
+3. **`jjEl.setHTML(html)` without `true`** — throws when html is non-empty.
 4. **Fetching template/style inside `connectedCallback`** — fetch at module scope so the network request is shared.
 5. **Not awaiting `Element.defined`** — markup may be parsed before the element is defined, causing flaky upgrades.
 6. **Breaking the chain with `.ref` unnecessarily** — use wrapper methods first; reach for `.ref` only when no wrapper method exists.
+7. **Using `.ref.value` for common value updates** — prefer `getValue()` / `setValue(...)` for wrapper-level reads/writes.
 
 ## Pitfall Prevention Rules (Component Work)
 

package/skills/references/css-improvements.md

@@ -62,15 +62,16 @@ button {
 }
 ```
 
-## Loading stylesheets
+## Loading css files
 
 ```js
-import { JJHE, fetchStyle } from 'jj'
+import { JJD, JJHE, fetchStyle } from 'jj'
 
 const h = JJHE.tree
+const jjDoc = JJD.from(document)
 
 // Hint browser to start loading early
-document.head.addChild(
+jjDoc.find('head', true).addChild(
     h('link', {
         href: import.meta.resolve('./theme.css'),
         rel: 'preload',

package/skills/references/eventing-patterns.md

@@ -3,15 +3,15 @@
 ## Native event listeners
 
 ```js
-el.on('click', handler) // addEventListener
-el.off('click', handler) // removeEventListener (same function reference)
-el.trigger('click') // dispatchEvent(new Event('click'))
+jjEl.on('click', handler) // addEventListener
+jjEl.off('click', handler) // removeEventListener (same function reference)
+jjEl.triggerEvent('click') // creates and dispatches Event('click')
 ```
 
 The handler `this` inside `.on()` is bound to the JJ wrapper instance. Use `this.ref` to access the native element:
 
 ```js
-btn.on('click', function () {
+jjBtn.on('click', function () {
     // this → the JJHE wrapper
     // this.ref → the HTMLButtonElement
     console.log(this.ref.textContent)
@@ -54,10 +54,16 @@ new CustomEvent('internal-ready', { bubbles: false, composed: false })
 ## Event delegation
 
 ```js
-const list = doc.find('#list', true)
-list.on('click', (e) => {
-    const item = e.target.closest('[data-id]')
-    if (item) handleClick(item.dataset.id)
+import { JJD } from 'jj'
+
+const jjDoc = JJD.from(document)
+const jjList = jjDoc.find('#list', true)
+jjList.on('click', (e) => {
+    if (!(e.target instanceof Element)) {
+        return
+    }
+    const itemEl = e.target.closest('[data-id]')
+    if (itemEl) handleClick(itemEl.dataset.id)
 })
 ```
 
@@ -65,7 +71,7 @@ list.on('click', (e) => {
 
 ```js
 const ctrl = new AbortController()
-el.ref.addEventListener('click', handler, { signal: ctrl.signal })
+jjEl.ref.addEventListener('click', handler, { signal: ctrl.signal })
 // later:
 ctrl.abort() // removes listener
 ```

package/skills/references/jquery-to-jj-translation.md

@@ -7,8 +7,8 @@ jQuery provides chainable selection and DOM operations. JJ is similar in API fee
 | jQuery                         | JJ equivalent                                                                     |
 | ------------------------------ | --------------------------------------------------------------------------------- |
 | `$('#id')`                     | `JJD.from(document).find('#id')`                                                  |
-| `$('.cls')` (first match)      | `doc.find('.cls')`                                                                |
-| `$('.cls')` (all matches)      | `doc.findAll('.cls')`                                                             |
+| `$('.cls')` (first match)      | `jjDoc.find('.cls')`                                                              |
+| `$('.cls')` (all matches)      | `jjDoc.findAll('.cls')`                                                           |
 | `.addClass()` / `.removeClass` | `.addClass()` / `.rmClass()`                                                      |
 | `.swClass(cls, bool?)`         | `.swClass(cls, force?)` — explicit when force is provided, auto-flip when omitted |
 | `.attr(name, val)` (write)     | `.setAttr(name, val)`                                                             |
@@ -36,8 +36,8 @@ $('.card').addClass('active').css('color', 'red')
 JJ:
 
 ```js
-const doc = JJD.from(document)
-doc.findAll('.card').forEach((card) => card.addClass('active').setStyle('color', 'red'))
+const jjDoc = JJD.from(document)
+jjDoc.findAll('.card').forEach((jjCard) => jjCard.addClass('active').setStyle('color', 'red'))
 ```
 
 ## HTML write safety
@@ -51,8 +51,8 @@ $('#msg').html(userInput) // XSS risk
 JJ requires explicit acknowledgement:
 
 ```js
-doc.find('#msg').setHTML(trustedMarkup, true) // must pass true
-doc.find('#msg').setText(userInput) // safe for user content
+jjDoc.find('#msg').setHTML(trustedMarkup, true) // must pass true
+jjDoc.find('#msg').setText(userInput) // safe for user content
 ```
 
 ## Event delegation
@@ -66,7 +66,10 @@ $(document).on('click', '.item', handler)
 JJ — use native event delegation via `matches`:
 
 ```js
-doc.on('click', (e) => {
+jjDoc.on('click', (e) => {
+    if (!(e.target instanceof Element)) {
+        return
+    }
     if (e.target.matches('.item')) handler(e)
 })
 ```

package/skills/references/lit-to-jj-translation.md

@@ -13,7 +13,7 @@ Lit adds reactive properties, template literals, and scoped CSS on top of native
 | `html\`<div>\``           | `JJHE.tree('div', …)` or `JJHE.create('div')`                              |
 | `@event="${handler}"`     | `.on('event', handler)` in `connectedCallback`                             |
 | `updated()` hook          | Call `#render()` from setters that change visible state                    |
-| `this.renderRoot.query…`  | `this.#root.find(selector)`                                                |
+| `this.renderRoot.query…`  | `this.#jjShadow.find(selector)`                                            |
 
 ## Component example
 
@@ -46,12 +46,12 @@ export class MyCounter extends HTMLElement {
     static defined = defineComponent('my-counter', MyCounter)
 
     #count = 0
-    #root = null
+    #jjShadow = null
     #isInitialized = false
 
     constructor() {
         super()
-        this.#root = JJHE.from(this).setShadow('open').getShadow(true)
+        this.#jjShadow = JJHE.from(this).setShadow('open').getShadow(true)
     }
 
     attributeChangedCallback(name, oldValue, newValue) {
@@ -67,7 +67,7 @@ export class MyCounter extends HTMLElement {
 
     async connectedCallback() {
         if (!this.#isInitialized) {
-            this.#root
+            this.#jjShadow
                 .init('<button id="btn">0</button>', await stylePromise)
                 .find('#btn', true)
                 .on('click', () => {
@@ -79,7 +79,7 @@ export class MyCounter extends HTMLElement {
     }
 
     #render() {
-        this.#root?.find('#btn')?.setText(String(this.#count))
+        this.#jjShadow?.find('#btn')?.setText(String(this.#count))
     }
 }
 ```

package/skills/references/querying-patterns.md

@@ -5,16 +5,16 @@
 Always start from a wrapped container — most commonly the document or a shadow root:
 
 ```js
-const doc = JJD.from(document)
-const shadow = this.#root // JJSR inside a custom element
+const jjDoc = JJD.from(document)
+const jjShadow = this.#jjShadow // JJSR inside a custom element
 ```
 
 ## find — first match
 
 ```js
-const card = doc.find('.card') // null when absent
-const app = doc.find('#app', true) // throws TypeError when absent
-const btn = shadow.find('#submit') // scoped to shadow root
+const jjCard = jjDoc.find('.card') // null when absent
+const jjApp = jjDoc.find('#app', true) // throws ReferenceError when absent
+const jjBtn = jjShadow.find('#submit') // scoped to shadow root
 ```
 
 Pass `true` as the second argument when the element is required. This produces a clearer error than a null-access crash later.
@@ -22,9 +22,9 @@ Pass `true` as the second argument when the element is required. This produces a
 You can use it in combination with a more specific query to simultaneously assert your expectations. For example, if you want a reference to a button with the id `submit`, you could write:
 
 ```js
-const submitBtn = doc.find('#submit-btn', true)
+const jjSubmitBtn = jjDoc.find('#submit-btn', true)
 
-if (!(submitBtn instanceof HTMLButtonElement)) {
+if (!(jjSubmitBtn.ref instanceof HTMLButtonElement)) {
     throw new Error('Expected #submit-btn to be an HTMLButtonElement.')
 }
 ```
@@ -34,7 +34,7 @@ But a shorter and more expressive way to write this is:
 ```js
 // This will throw an exception if an element with id is not found
 // OR if it's found but not a button
-const submitBtn = doc.find('button#submit-btn', true)
+const jjSubmitBtn = jjDoc.find('button#submit-btn', true)
 ```
 
 This helps catch errors early and narrow down troubleshooting.
@@ -43,19 +43,19 @@ When `find` returns a wrapper, keep the wrapper unless you need a native API tha
 
 ```js
 // ✅ keep wrapper value
-const jjSubmitBtn = doc.find('button#submit-btn', true)
+const jjSubmitBtn = jjDoc.find('button#submit-btn', true)
 jjSubmitBtn.on('click', onSubmit)
 
 // ❌ avoid unwrap + re-wrap noise
-const submitRef = doc.find('button#submit-btn', true).ref
+const submitRef = jjDoc.find('button#submit-btn', true).ref
 const jjSubmitBtnAgain = JJHE.from(submitRef)
 ```
 
 ## findAll — all matches
 
 ```js
-const items = doc.findAll('li.item') // always an array (may be empty)
-items.forEach((item) => item.addClass('loaded'))
+const jjItems = jjDoc.findAll('li.item') // always an array (may be empty)
+jjItems.forEach((jjItem) => jjItem.addClass('loaded'))
 ```
 
 ## closest — ancestor lookup
@@ -63,16 +63,19 @@ items.forEach((item) => item.addClass('loaded'))
 Use `.closest()` on element wrappers for event delegation or tree navigation:
 
 ```js
-doc.on('click', (e) => {
-    const item = JJHE.from(e.target).closest('[data-item-id]')
-    if (item) handleItemClick(item.getAttr('data-item-id'))
+jjDoc.on('click', (e) => {
+    if (!(e.target instanceof Node)) {
+        return
+    }
+    const jjItem = JJHE.from(e.target).closest('[data-item-id]')
+    if (jjItem) handleItemClick(jjItem.getAttr('data-item-id'))
 })
 ```
 
 ## fromId — direct ID lookup
 
 ```js
-const btn = JJHE.fromId('submit-btn') // typed as JJHE<HTMLButtonElement>
+const jjBtn = JJHE.fromId('submit-btn') // typed as JJHE<HTMLButtonElement>
 ```
 
 ## When to use .ref for queries

package/skills/references/react-to-jj-translation.md

@@ -31,12 +31,12 @@ JJ:
 import { JJHE } from 'jj'
 
 let count = 0
-const btn = JJHE.create('button').setText('0')
-btn.on('click', () => {
+const jjBtn = JJHE.create('button').setText('0')
+jjBtn.on('click', () => {
     count++
-    btn.setText(String(count))
+    jjBtn.setText(String(count))
 })
-document.body.appendChild(btn.ref)
+document.body.appendChild(jjBtn.ref)
 ```
 
 ## Component props → observed attributes
@@ -73,7 +73,7 @@ JJ — child dispatches, parent listens:
 JJHE.from(this).triggerCustomEvent('todo-toggle', { id: this.#id })
 
 // parent
-container.on('todo-toggle', (e) => handleToggle(e.detail.id))
+jjContainer.on('todo-toggle', (e) => handleToggle(e.detail.id))
 ```
 
 ## Browser references

package/skills/references/svelte-to-jj-translation.md

@@ -32,9 +32,9 @@ JJ:
 import { JJHE } from 'jj'
 
 let count = 0
-const btn = JJHE.create('button').setText('0')
-btn.on('click', () => btn.setText(String(++count)))
-document.body.appendChild(btn.ref)
+const jjBtn = JJHE.create('button').setText('0')
+jjBtn.on('click', () => jjBtn.setText(String(++count)))
+document.body.appendChild(jjBtn.ref)
 ```
 
 ## Outbound events

package/skills/references/testing-with-jsdom.md

@@ -33,9 +33,9 @@ import { JJHE } from '../src/index.js'
 describe('JJHE', () => {
     describe('static create()', () => {
         it('creates element from tag name', () => {
-            const div = JJHE.create('div')
-            assert.ok(div instanceof JJHE)
-            assert.strictEqual(div.ref.tagName, 'DIV')
+            const jjDiv = JJHE.create('div')
+            assert.ok(jjDiv instanceof JJHE)
+            assert.strictEqual(jjDiv.ref.tagName, 'DIV')
         })
 
         it('throws TypeError for non-string tagName', () => {
@@ -68,12 +68,12 @@ it('renders title in shadow', async () => {
 
 ```js
 it('dispatches todo-toggle with detail', () => {
-    const el = JJHE.create('div')
+    const jjEl = JJHE.create('div')
     let captured = null
-    el.on('todo-toggle', (e) => {
+    jjEl.on('todo-toggle', (e) => {
         captured = e.detail
     })
-    el.triggerCustomEvent('todo-toggle', { id: 1, done: true })
+    jjEl.triggerCustomEvent('todo-toggle', { id: 1, done: true })
     assert.deepStrictEqual(captured, { id: 1, done: true })
 })
 ```

package/skills/references/vue-to-jj-translation.md

@@ -30,12 +30,12 @@ JJ:
 import { JJHE } from 'jj'
 
 let message = ''
-const p = JJHE.create('p').setText('')
-const input = JJHE.create('input')
+const jjMessage = JJHE.create('p').setText('')
+const jjInput = JJHE.create('input')
     .setAttr('type', 'text')
-    .on('input', (e) => {
-        message = e.target.value
-        p.setText(message)
+    .on('input', () => {
+        message = jjInput.getValue()
+        jjMessage.setText(message)
     })
 ```
 
@@ -62,7 +62,7 @@ set count(v) {
 ## v-for replacement
 
 ```js
-list.addChildMap(items, (item) => JJHE.tree('li', { class: 'item' }, item.label))
+jjList.addChildMap(items, (item) => JJHE.tree('li', { class: 'item' }, item.label))
 ```
 
 ## Browser references

package/skills/references/web-components-patterns.md

@@ -37,10 +37,16 @@ use `defineComponent()` which also calls `customElements.whenDefined()`.
 const templatePromise = fetchTemplate(import.meta.resolve('./my-component.html'))
 const stylePromise    = fetchStyle(import.meta.resolve('./my-component.css'))
 
+constructor() {
+    super()
+    this.#jjHost = JJHE.from(this).setShadow('open')
+    this.#jjShadow = this.#jjHost.getShadow(true)
+}
+
 async connectedCallback() {
-    // setShadow(mode) in the constructor, then initShadow(template, ...styles) here
-    JJHE.from(this).initShadow(await templatePromise, await stylePromise)
-    this.#root.find('#btn').on('click', this.#handleClick)
+    // setShadow(mode) in the constructor, then initialize once here
+    this.#jjHost.initShadow(await templatePromise, await stylePromise)
+    this.#jjShadow.find('#btn', true).on('click', this.#handleClick)
     this.#render()
 }
 ```
@@ -63,8 +69,8 @@ attributeChangedCallback(name, oldValue, newValue) {
 // attr2prop fires attributeChangedCallback BEFORE connectedCallback on initial parse.
 // Guard renders until shadow is ready:
 #render() {
-    if (!this.#root) return
-    this.#root.find('[data-role="name"]')?.setText(this.#userName)
+    if (!this.#jjShadow) return
+    this.#jjShadow.find('[data-role="name"]')?.setText(this.#userName)
 }
 ```
 
@@ -74,8 +80,8 @@ Skip `setShadow` and update children directly when page-level styling should app
 
 ```js
 async connectedCallback() {
-    this.#root = JJHE.from(this)
-    this.#root.setTemplate(await templatePromise)
+    this.#jjHost = JJHE.from(this)
+    this.#jjHost.setTemplate(await templatePromise)
     this.#render()
 }
 ```