@wippy-fe/webcomponent-core 0.0.30 → 0.0.31

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wippy-fe/webcomponent-core",
-  "version": "0.0.30",
-  "description": "Framework-agnostic base class for Wippy web components — shadow DOM, CSS loading, schema-driven prop parsing, and lifecycle management.",
+  "version": "0.0.31",
+  "description": "Framework-agnostic base class for Wippy web components — shadow DOM, CSS loading, schema-driven prop parsing, and lifecycle management.",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -11,8 +11,8 @@
   ],
   "peerDependencies": {
     "@iconify/vue": "^5.0.0",
-    "@wippy-fe/proxy": "0.0.30",
-    "@wippy-fe/shared": "0.0.30"
+    "@wippy-fe/proxy": "0.0.31",
+    "@wippy-fe/shared": "0.0.31"
   },
   "license": "UNLICENSED"
 }

package/src/base-element.host.test.ts

@@ -5,7 +5,7 @@
  * the managed-layout shell's content resolvers. And the cleanup path
  * in `disconnectedCallback` that drops stale wires on detach.
  */
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { WippyElement } from './base-element.ts'
 
 // `ElementInternals.states` shim lives in `vitest.setup.ts` (gen-2-chat
@@ -77,6 +77,142 @@ describe('wippyElement.disconnectedCallback wire cleanup', () => {
   })
 })
 
+describe('wippyElement.reactive — opt-in reactive adapter', () => {
+  // Element with a `count` schema prop so attribute changes are observable.
+  interface ReactiveProps { count: number }
+  interface ReactiveEvents { tick: { n: number } }
+  class ReactiveEl extends WippyElement<ReactiveProps, ReactiveEvents> {
+    static get wippyConfig() {
+      return {
+        propsSchema: { properties: { count: { type: 'integer' as const } } },
+        hostCssKeys: [],
+      }
+    }
+
+    /** Test-only handle for assertions inside lifecycle hooks. */
+    public observedHook: { props: ReactiveProps, errors: string[] } | null = null
+    /** True iff the adapter has been lazy-allocated. */
+    public get adapterAllocated(): boolean {
+      return (this as unknown as { _reactive: unknown })._reactive !== null
+    }
+
+    protected onMount(): void {}
+    protected onUnmount(): void {}
+
+    protected onPropsChanged(props: ReactiveProps, errors: string[]): void {
+      this.observedHook = { props, errors }
+    }
+  }
+  const reactiveTag = `wippy-reactive-${Math.random().toString(36).slice(2)}`
+  customElements.define(reactiveTag, ReactiveEl)
+
+  it('does NOT allocate the adapter when never accessed', () => {
+    const el = document.createElement(reactiveTag) as ReactiveEl
+    el.setAttribute('count', '1')
+    document.body.appendChild(el)
+    el.setAttribute('count', '2')
+    expect(el.adapterAllocated).toBe(false)
+    expect(el.observedHook?.props.count).toBe(2)
+    el.remove()
+  })
+
+  it('lazy-allocates on first `this.reactive` access and seeds from current attributes', () => {
+    const el = document.createElement(reactiveTag) as ReactiveEl
+    el.setAttribute('count', '7')
+    document.body.appendChild(el)
+    expect(el.adapterAllocated).toBe(false)
+
+    const reactive = (el as unknown as { reactive: ReturnType<ReactiveEl['onPropsChanged']> extends void ? any : never }).reactive
+    expect(el.adapterAllocated).toBe(true)
+    expect((reactive as any).props.value).toEqual({ count: 7 })
+    el.remove()
+  })
+
+  it('fires subscribers on attribute change after allocation', () => {
+    const el = document.createElement(reactiveTag) as ReactiveEl
+    el.setAttribute('count', '1')
+    document.body.appendChild(el)
+
+    const reactive = (el as any).reactive
+    const listener = vi.fn()
+    reactive.props.subscribe(listener)
+
+    el.setAttribute('count', '2')
+    expect(listener).toHaveBeenCalledTimes(1)
+    expect(listener).toHaveBeenCalledWith({ count: 2 }, [])
+
+    el.setAttribute('count', '3')
+    expect(listener).toHaveBeenCalledTimes(2)
+    el.remove()
+  })
+
+  it('events.emit dispatches a bubbling/composed CustomEvent on the element', () => {
+    const el = document.createElement(reactiveTag) as ReactiveEl
+    document.body.appendChild(el)
+
+    const reactive = (el as any).reactive
+    const events: Event[] = []
+    el.addEventListener('tick', (e) => {
+      events.push(e)
+    })
+
+    reactive.events.emit('tick', { n: 99 })
+    expect(events).toHaveLength(1)
+    const ev = events[0] as CustomEvent<{ n: number }>
+    expect(ev.detail).toEqual({ n: 99 })
+    expect(ev.bubbles).toBe(true)
+    expect(ev.composed).toBe(true)
+    el.remove()
+  })
+
+  it('disconnectedCallback disposes the adapter; subscribers stop firing', () => {
+    const el = document.createElement(reactiveTag) as ReactiveEl
+    document.body.appendChild(el)
+
+    const reactive = (el as any).reactive
+    const listener = vi.fn()
+    reactive.props.subscribe(listener)
+
+    el.remove()
+    expect(el.adapterAllocated).toBe(false)
+
+    // Re-append with a new attribute; the OLD subscriber must not fire.
+    el.setAttribute('count', '50')
+    document.body.appendChild(el)
+    el.setAttribute('count', '51')
+    expect(listener).not.toHaveBeenCalled()
+    el.remove()
+  })
+
+  it('after reconnect, a fresh adapter is allocated on next .reactive access', () => {
+    const el = document.createElement(reactiveTag) as ReactiveEl
+    document.body.appendChild(el)
+
+    const first = (el as any).reactive
+    el.remove()
+    document.body.appendChild(el)
+
+    const second = (el as any).reactive
+    expect(second).not.toBe(first)
+    el.remove()
+  })
+
+  it('legacy onPropsChanged override still fires alongside reactive', () => {
+    const el = document.createElement(reactiveTag) as ReactiveEl
+    el.setAttribute('count', '1')
+    document.body.appendChild(el)
+    // Force-allocate adapter
+    const reactive = (el as any).reactive
+    const listener = vi.fn()
+    reactive.props.subscribe(listener)
+
+    el.setAttribute('count', '2')
+    expect(listener).toHaveBeenCalledTimes(1)
+    expect(el.observedHook?.props.count).toBe(2)
+    el.remove()
+  })
+})
+
 describe('wippyElement reconnect — no shadow-child accumulation', () => {
   // R3 regression: previously `connectedCallback` re-ran the full mount
   // path (CSS injection + container append) on every reconnect. The

package/src/base-element.ts

@@ -1,9 +1,11 @@
+import type { ReactiveAdapter } from './reactive-adapter.ts'
 import type { WippyElementConfig } from './types.ts'
 import { addCollection } from '@iconify/vue'
 import { addIcons, define } from '@wippy-fe/proxy'
 import { injectInlineCss, loadHostCss } from './css-loader.ts'
 import { getWippyHost } from './host-scope.ts'
 import { parseProps } from './prop-parser.ts'
+import { ReactiveAdapterImpl } from './reactive-adapter.ts'
 
 /**
  * Abstract base class for Wippy web components.
@@ -36,13 +38,42 @@ import { parseProps } from './prop-parser.ts'
  * Note: `disconnectedCallback` does NOT clear the shadow root or the
  * stored container — they're reused on reconnect.
  */
-export abstract class WippyElement<Props = Record<string, unknown>> extends HTMLElement {
+export abstract class WippyElement<
+  Props = Record<string, unknown>,
+  Events = Record<string, unknown>,
+> extends HTMLElement {
   private _internals!: ElementInternals
   private _contentObserver: MutationObserver | null = null
   /** True after the first successful connectedCallback completes. */
   private _initialized: boolean = false
   /** Container div created on first connect; reused on subsequent connects. */
   private _container: HTMLElement | null = null
+  /**
+   * Opt-in reactive adapter. Lazy-allocated on first `this.reactive`
+   * access, disposed on `disconnectedCallback`, re-allocated on next
+   * access after reconnect. Subclasses that never touch `this.reactive`
+   * pay zero allocation cost — `notifyProps`/`notifyContent` short-circuit
+   * on the null guard.
+   */
+  private _reactive: ReactiveAdapterImpl<Props, Events> | null = null
+  /**
+   * Cached results of the most recent `parseProps` + `validateProps`
+   * pass. Set by `connectedCallback` and `attributeChangedCallback`.
+   * Read by `get reactive()` to avoid re-parsing on lazy allocation —
+   * means `validateProps` only ever runs once per attribute change,
+   * even for consumers that touch `this.reactive` inside `onMount`.
+   */
+  private _lastProps: Props | null = null
+  private _lastErrors: readonly string[] = []
+  private _lastContent: string | null = null
+
+  /**
+   * Phantom field to retain the `Events` type parameter so it shows up in
+   * type errors / `Reflect.get` shape. Adapter typing reads it indirectly
+   * via the generic.
+   * @internal
+   */
+  declare readonly _events: Events
 
   /**
    * Override to provide the component's configuration.
@@ -101,6 +132,65 @@ export abstract class WippyElement<Props = Record<string, unknown>> extends HTML
     }))
   }
 
+  /**
+   * Opt-in reactive adapter — framework-agnostic. Subscribe to prop
+   * changes, content changes, or emit typed events from a non-Vue
+   * consumer without re-rolling reactivity.
+   *
+   * ```ts
+   * class MyEl extends WippyElement<{ count: number }, { tick: { n: number } }> {
+   *   protected onMount() {
+   *     const ctrl = new AbortController()
+   *     this.reactive.props.subscribe(({ count }) => {
+   *       this.shadowRoot!.querySelector('.n')!.textContent = String(count)
+   *     }, { signal: ctrl.signal, immediate: true })
+   *   }
+   *   tick(n: number) { this.reactive.events.emit('tick', { n }) }
+   * }
+   * ```
+   *
+   * Allocation cost is zero unless this getter is touched. Disposed on
+   * `disconnectedCallback`; a fresh adapter is allocated on the next
+   * access after reconnect.
+   */
+  protected get reactive(): ReactiveAdapter<Props, Events> {
+    if (!this._reactive) {
+      const config = (this.constructor as typeof WippyElement).wippyConfig
+      const hasContent = !!config.contentTemplate
+      // Reuse the cached parse result from the most recent
+      // `connectedCallback` / `attributeChangedCallback` whenever we
+      // have one; otherwise fall back to a fresh parse (this happens
+      // when `reactive` is touched before the element is ever
+      // connected — rare but legal).
+      let props: Props
+      let errors: readonly string[]
+      if (this._lastProps !== null) {
+        props = this._lastProps
+        errors = this._lastErrors
+      }
+      else {
+        const parsed = parseProps(this, config.propsSchema)
+        if (config.validateProps) {
+          parsed.errors.push(...config.validateProps(parsed.props))
+        }
+        props = parsed.props as Props
+        errors = parsed.errors
+        this._lastProps = props
+        this._lastErrors = errors
+      }
+      const content = hasContent
+        ? (this._lastContent ?? this._extractContent(config.contentTemplate!))
+        : null
+      if (hasContent && this._lastContent === null)
+        this._lastContent = content
+      this._reactive = new ReactiveAdapterImpl<Props, Events>(
+        { props, errors, content, hasContent },
+        this.emitEvent.bind(this),
+      )
+    }
+    return this._reactive
+  }
+
   // ── Lifecycle ──────────────────────────────────────────────
 
   connectedCallback(): void {
@@ -154,13 +244,23 @@ export abstract class WippyElement<Props = Record<string, unknown>> extends HTML
         errors.push(...config.validateProps(props))
       }
       const typedProps = props as Props
+      // Cache so a lazy `get reactive()` call from inside `onMount`
+      // doesn't re-parse / re-validate.
+      this._lastProps = typedProps
+      this._lastErrors = errors
 
       // 7b. Extract children content (if contentTemplate configured)
       let initialContent: string | null = null
       if (config.contentTemplate) {
         initialContent = this._extractContent(config.contentTemplate)
+        this._lastContent = initialContent
         this._contentObserver = new MutationObserver(() => {
           const content = this._extractContent(config.contentTemplate!)
+          this._lastContent = content
+          // Fan out to the reactive adapter first so subclass overrides of
+          // `onContentChanged` that read `this.reactive.content.value` see
+          // the new value. No-op when the adapter hasn't been allocated.
+          this._reactive?.notifyContent(content)
           this.onContentChanged(content)
         })
         this._contentObserver.observe(this, {
@@ -207,6 +307,17 @@ export abstract class WippyElement<Props = Record<string, unknown>> extends HTML
     this.onUnmount()
     this.emitEvent('unload')
     this._internals.states.clear()
+    // Drop the reactive adapter so subscribers from this attachment are
+    // cleared and a fresh adapter is allocated on the next `this.reactive`
+    // access (i.e. after reconnect).
+    this._reactive?.dispose()
+    this._reactive = null
+    // Clear cached parse state — `connectedCallback` re-populates on
+    // reconnect; before then, a lazy `get reactive()` access should
+    // re-parse from current attributes (rare path).
+    this._lastProps = null
+    this._lastErrors = []
+    this._lastContent = null
     // Drop panel-context wires so a detached element held by a
     // consumer (or re-inserted into a different panel) doesn't carry
     // stale wires that would silently misattribute. The resolver
@@ -223,7 +334,15 @@ export abstract class WippyElement<Props = Record<string, unknown>> extends HTML
     if (config.validateProps) {
       errors.push(...config.validateProps(props))
     }
-    this.onPropsChanged(props as Props, errors)
+    const typedProps = props as Props
+    this._lastProps = typedProps
+    this._lastErrors = errors
+    // Fan out to the reactive adapter BEFORE the legacy hook so subclasses
+    // that override `onPropsChanged` AND read `this.reactive.props.value`
+    // inside it see consistent state. No-op when the adapter hasn't been
+    // lazy-allocated.
+    this._reactive?.notifyProps(typedProps, errors)
+    this.onPropsChanged(typedProps, errors)
   }
 
   // ── Hooks ──────────────────────────────────────────────────

package/src/index.ts

@@ -5,6 +5,15 @@ export type { BroadcastEnvelope, LayoutBusBound } from './host-bus.ts'
 export { getWippyHost } from './host-scope.ts'
 export { attrToCamel, parseProps } from './prop-parser.ts'
 export type { ParseResult } from './prop-parser.ts'
+export type {
+  ContentListener,
+  ContentSubscription,
+  EventEmitterHandle,
+  PropsListener,
+  PropsSubscription,
+  ReactiveAdapter,
+  SubscribeOptions,
+} from './reactive-adapter.ts'
 export type {
   HostCssKey,
   WippyElementConfig,

package/src/reactive-adapter.test.ts

@@ -0,0 +1,290 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { ReactiveAdapterImpl } from './reactive-adapter.ts'
+
+// ─────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────
+
+interface TestProps {
+  count: number
+  label: string
+}
+
+interface TestEvents {
+  tick: { n: number }
+  reset: { reason: string }
+}
+
+function makeAdapter(initial?: {
+  props?: TestProps
+  errors?: string[]
+  content?: string | null
+  hasContent?: boolean
+}) {
+  const emit = vi.fn()
+  const adapter = new ReactiveAdapterImpl<TestProps, TestEvents>(
+    {
+      props: initial?.props ?? { count: 0, label: 'init' },
+      errors: initial?.errors ?? [],
+      content: initial?.content ?? null,
+      hasContent: initial?.hasContent ?? false,
+    },
+    emit,
+  )
+  return { adapter, emit }
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+// ─────────────────────────────────────────────────────────────
+// props subscription
+// ─────────────────────────────────────────────────────────────
+
+describe('reactiveAdapter — props subscription', () => {
+  it('exposes the initial props via `.value` and `.errors`', () => {
+    const { adapter } = makeAdapter({
+      props: { count: 5, label: 'hello' },
+      errors: ['oops'],
+    })
+    expect(adapter.props.value).toEqual({ count: 5, label: 'hello' })
+    expect(adapter.props.errors).toEqual(['oops'])
+  })
+
+  it('fires listeners on notifyProps with new values', () => {
+    const { adapter } = makeAdapter()
+    const listener = vi.fn()
+    adapter.props.subscribe(listener)
+
+    adapter.notifyProps({ count: 1, label: 'one' }, ['e'])
+
+    expect(listener).toHaveBeenCalledTimes(1)
+    expect(listener).toHaveBeenCalledWith({ count: 1, label: 'one' }, ['e'])
+    expect(adapter.props.value).toEqual({ count: 1, label: 'one' })
+    expect(adapter.props.errors).toEqual(['e'])
+  })
+
+  it('returned unsubscribe function stops further callbacks', () => {
+    const { adapter } = makeAdapter()
+    const listener = vi.fn()
+    const unsub = adapter.props.subscribe(listener)
+
+    adapter.notifyProps({ count: 1, label: 'a' }, [])
+    unsub()
+    adapter.notifyProps({ count: 2, label: 'b' }, [])
+
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  it('abortSignal.abort() cancels the subscription', () => {
+    const { adapter } = makeAdapter()
+    const ctrl = new AbortController()
+    const listener = vi.fn()
+    adapter.props.subscribe(listener, { signal: ctrl.signal })
+
+    adapter.notifyProps({ count: 1, label: 'a' }, [])
+    ctrl.abort()
+    adapter.notifyProps({ count: 2, label: 'b' }, [])
+
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  it('does NOT subscribe when the signal is already aborted', () => {
+    const { adapter } = makeAdapter()
+    const ctrl = new AbortController()
+    ctrl.abort()
+    const listener = vi.fn()
+    adapter.props.subscribe(listener, { signal: ctrl.signal })
+
+    adapter.notifyProps({ count: 1, label: 'a' }, [])
+
+    expect(listener).not.toHaveBeenCalled()
+  })
+
+  it('options.immediate fires the listener synchronously with current state', () => {
+    const { adapter } = makeAdapter({
+      props: { count: 7, label: 'now' },
+      errors: ['warn'],
+    })
+    const listener = vi.fn()
+    adapter.props.subscribe(listener, { immediate: true })
+
+    expect(listener).toHaveBeenCalledTimes(1)
+    expect(listener).toHaveBeenCalledWith({ count: 7, label: 'now' }, ['warn'])
+  })
+
+  it('multiple subscribers all receive updates; unsubscribing one does not affect others', () => {
+    const { adapter } = makeAdapter()
+    const a = vi.fn()
+    const b = vi.fn()
+    const c = vi.fn()
+    adapter.props.subscribe(a)
+    const unsubB = adapter.props.subscribe(b)
+    adapter.props.subscribe(c)
+
+    adapter.notifyProps({ count: 1, label: 'x' }, [])
+    unsubB()
+    adapter.notifyProps({ count: 2, label: 'y' }, [])
+
+    expect(a).toHaveBeenCalledTimes(2)
+    expect(b).toHaveBeenCalledTimes(1)
+    expect(c).toHaveBeenCalledTimes(2)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────
+// events emitter
+// ─────────────────────────────────────────────────────────────
+
+describe('reactiveAdapter — AbortSignal hygiene', () => {
+  it('manual unsub() removes the abort listener from the signal (no leak)', () => {
+    const { adapter } = makeAdapter()
+    const ctrl = new AbortController()
+    const removeSpy = vi.spyOn(ctrl.signal, 'removeEventListener')
+    const listener = vi.fn()
+    const unsub = adapter.props.subscribe(listener, { signal: ctrl.signal })
+
+    unsub()
+
+    expect(removeSpy).toHaveBeenCalledWith('abort', expect.any(Function))
+  })
+
+  it('does not double-fire when abort fires after manual unsub', () => {
+    const { adapter } = makeAdapter()
+    const ctrl = new AbortController()
+    const listener = vi.fn()
+    const unsub = adapter.props.subscribe(listener, { signal: ctrl.signal })
+
+    unsub()
+    ctrl.abort() // would re-trigger unsub if abort listener weren't removed
+
+    // notifyProps should still find no listeners
+    adapter.notifyProps({ count: 1, label: 'x' }, [])
+    expect(listener).not.toHaveBeenCalled()
+  })
+})
+
+describe('reactiveAdapter — re-entrant notify during immediate fire', () => {
+  it('captures synchronous re-entrant notifyProps from inside immediate callback', () => {
+    const { adapter } = makeAdapter()
+    const seen: Array<{ count: number, label: string }> = []
+    let triggeredOnce = false
+    adapter.props.subscribe((props) => {
+      seen.push(props)
+      // Re-enter notifyProps from inside the listener (simulating a
+      // listener that synchronously triggers an attribute change).
+      if (!triggeredOnce) {
+        triggeredOnce = true
+        adapter.notifyProps({ count: 99, label: 'after-immediate' }, [])
+      }
+    }, { immediate: true })
+
+    // Expected: 1st call = immediate fire with initial state,
+    // 2nd call = synchronous notifyProps from inside listener.
+    // Without the order-swap fix, the 2nd call would be lost.
+    expect(seen).toEqual([
+      { count: 0, label: 'init' },
+      { count: 99, label: 'after-immediate' },
+    ])
+  })
+})
+
+describe('reactiveAdapter — events emitter', () => {
+  it('emit delegates to the provided DOM emit function', () => {
+    const { adapter, emit } = makeAdapter()
+    adapter.events.emit('tick', { n: 42 })
+    expect(emit).toHaveBeenCalledWith('tick', { n: 42 })
+  })
+
+  it('emit becomes a no-op after dispose', () => {
+    const { adapter, emit } = makeAdapter()
+    adapter.dispose()
+    adapter.events.emit('tick', { n: 1 })
+    expect(emit).not.toHaveBeenCalled()
+  })
+})
+
+// ─────────────────────────────────────────────────────────────
+// content subscription
+// ─────────────────────────────────────────────────────────────
+
+describe('reactiveAdapter — content', () => {
+  it('content is null when hasContent is false', () => {
+    const { adapter } = makeAdapter({ hasContent: false })
+    expect(adapter.content).toBeNull()
+  })
+
+  it('content exposes value + subscribe when hasContent is true', () => {
+    const { adapter } = makeAdapter({
+      hasContent: true,
+      content: 'initial-text',
+    })
+    expect(adapter.content?.value).toBe('initial-text')
+  })
+
+  it('fires content listeners on notifyContent', () => {
+    const { adapter } = makeAdapter({ hasContent: true, content: 'a' })
+    const listener = vi.fn()
+    adapter.content!.subscribe(listener)
+
+    adapter.notifyContent('b')
+
+    expect(listener).toHaveBeenCalledWith('b')
+    expect(adapter.content!.value).toBe('b')
+  })
+
+  it('immediate fires for content too', () => {
+    const { adapter } = makeAdapter({ hasContent: true, content: 'preset' })
+    const listener = vi.fn()
+    adapter.content!.subscribe(listener, { immediate: true })
+    expect(listener).toHaveBeenCalledWith('preset')
+  })
+})
+
+// ─────────────────────────────────────────────────────────────
+// dispose
+// ─────────────────────────────────────────────────────────────
+
+describe('reactiveAdapter — dispose', () => {
+  it('notifyProps becomes a no-op after dispose', () => {
+    const { adapter } = makeAdapter()
+    const listener = vi.fn()
+    adapter.props.subscribe(listener)
+
+    adapter.dispose()
+    adapter.notifyProps({ count: 99, label: 'after' }, [])
+
+    expect(listener).not.toHaveBeenCalled()
+  })
+
+  it('notifyContent becomes a no-op after dispose', () => {
+    const { adapter } = makeAdapter({ hasContent: true })
+    const listener = vi.fn()
+    adapter.content!.subscribe(listener)
+
+    adapter.dispose()
+    adapter.notifyContent('after')
+
+    expect(listener).not.toHaveBeenCalled()
+  })
+
+  it('subscribe after dispose returns a no-op unsub and never fires', () => {
+    const { adapter } = makeAdapter()
+    adapter.dispose()
+    const listener = vi.fn()
+    const unsub = adapter.props.subscribe(listener)
+
+    adapter.notifyProps({ count: 1, label: 'a' }, [])
+    expect(listener).not.toHaveBeenCalled()
+    expect(() => unsub()).not.toThrow()
+  })
+
+  it('dispose is idempotent', () => {
+    const { adapter } = makeAdapter()
+    expect(() => {
+      adapter.dispose()
+      adapter.dispose()
+    }).not.toThrow()
+  })
+})

package/src/reactive-adapter.ts

@@ -0,0 +1,220 @@
+/**
+ * Opt-in reactive adapter for `WippyElement`.
+ *
+ * Framework-agnostic primitive that lets non-Vue consumers subscribe to
+ * prop / content updates and emit typed events on a web component without
+ * pulling Vue (or any other reactivity library) into the core bundle.
+ *
+ * Access via `this.reactive` on a `WippyElement` subclass — the getter is
+ * lazy, so subclasses that never touch it pay zero allocation cost. See
+ * `base-element.ts:get reactive` for the bridge into the lifecycle.
+ *
+ * The `notifyProps` / `notifyContent` methods are package-visible: the
+ * base element calls them from `attributeChangedCallback` and the content
+ * MutationObserver callback respectively. They are NOT part of the public
+ * API consumers should reach for.
+ *
+ * Cleanup: `dispose()` runs from `disconnectedCallback`. All listener
+ * sets are cleared; subsequent notifyProps/notifyContent are no-ops; the
+ * `events.emit` becomes a no-op too. A fresh adapter is allocated on the
+ * next `this.reactive` access (i.e. after reconnect).
+ */
+
+export type PropsListener<Props> = (props: Props, errors: readonly string[]) => void
+export type ContentListener = (content: string | null) => void
+
+export interface SubscribeOptions {
+  /** Cancel the subscription when the signal aborts. */
+  signal?: AbortSignal
+  /** Fire the listener once synchronously with the current value. */
+  immediate?: boolean
+}
+
+export interface PropsSubscription<Props> {
+  /** Current parsed props. Always reflects the latest state. */
+  readonly value: Props
+  /** Current validation/parse errors. */
+  readonly errors: readonly string[]
+  /**
+   * Register a listener that fires whenever props change. Returns an
+   * unsubscribe function. Pass `options.signal` for AbortSignal-driven
+   * cleanup (e.g. tied to an element's lifetime). Pass
+   * `options.immediate: true` to fire once synchronously with the current
+   * value — useful when the subscriber is set up mid-flight.
+   *
+   * Note: `notifyProps` runs BEFORE the subclass `onPropsChanged()` hook.
+   * A subscriber added from inside `onPropsChanged()` therefore does NOT
+   * receive the currently-firing change — only the next one. Use
+   * `{ immediate: true }` to also see the current value.
+   */
+  subscribe: (listener: PropsListener<Props>, options?: SubscribeOptions) => () => void
+}
+
+export interface ContentSubscription {
+  /** Current `<template>` content text, or `null` if not set. */
+  readonly value: string | null
+  /** See `PropsSubscription.subscribe` for the same ordering caveat. */
+  subscribe: (listener: ContentListener, options?: SubscribeOptions) => () => void
+}
+
+export interface EventEmitterHandle<Events> {
+  /**
+   * Dispatch a typed `CustomEvent` (bubbles + composed, identical
+   * semantics to the protected `emitEvent` helper). The key is constrained
+   * to `keyof Events & string`, so consumers narrow `Events` to get
+   * autocomplete + payload-type checks.
+   *
+   * No-op after the adapter is disposed (i.e. after the element is
+   * detached). The element is the only event target — subscribers on
+   * the element itself receive the event.
+   */
+  emit: <K extends keyof Events & string>(event: K, detail: Events[K]) => void
+}
+
+export interface ReactiveAdapter<Props, Events> {
+  props: PropsSubscription<Props>
+  events: EventEmitterHandle<Events>
+  /**
+   * Present only when the element's `wippyConfig.contentTemplate` is set;
+   * `null` otherwise. Avoids fake `.value === null` semantics for elements
+   * that don't track children content.
+   */
+  content: ContentSubscription | null
+}
+
+/**
+ * Concrete implementation used by `WippyElement`. The `notify*` methods
+ * are intentionally exposed (not private) so the base-element can call
+ * them; consumers should never reach for them.
+ *
+ * @internal
+ */
+export class ReactiveAdapterImpl<Props, Events> implements ReactiveAdapter<Props, Events> {
+  private _props: Props
+  private _errors: readonly string[]
+  private _content: string | null
+  private _propsListeners = new Set<PropsListener<Props>>()
+  private _contentListeners = new Set<ContentListener>()
+  private _disposed = false
+  private _emitToDom: (eventName: string, detail?: unknown) => void
+
+  readonly props: PropsSubscription<Props>
+  readonly events: EventEmitterHandle<Events>
+  readonly content: ContentSubscription | null
+
+  constructor(
+    initial: {
+      props: Props
+      errors: readonly string[]
+      content: string | null
+      hasContent: boolean
+    },
+    emitToDom: (eventName: string, detail?: unknown) => void,
+  ) {
+    this._props = initial.props
+    this._errors = initial.errors
+    this._content = initial.content
+    this._emitToDom = emitToDom
+
+    // Each getter / closure below runs with the surrounding object literal
+    // as `this`, not the class instance — so we have to capture the
+    // instance explicitly here.
+    // eslint-disable-next-line ts/no-this-alias
+    const self = this
+
+    this.props = {
+      get value() {
+        return self._props
+      },
+      get errors() {
+        return self._errors
+      },
+      subscribe(listener, options) {
+        return self._subscribeProps(listener, options)
+      },
+    }
+
+    this.events = {
+      emit(event, detail) {
+        if (self._disposed)
+          return
+        self._emitToDom(event as string, detail)
+      },
+    }
+
+    this.content = initial.hasContent
+      ? {
+          get value() {
+            return self._content
+          },
+          subscribe(listener, options) {
+            return self._subscribeContent(listener, options)
+          },
+        }
+      : null
+  }
+
+  /** @internal */
+  notifyProps(props: Props, errors: readonly string[]): void {
+    if (this._disposed)
+      return
+    this._props = props
+    this._errors = errors
+    for (const listener of this._propsListeners)
+      listener(props, errors)
+  }
+
+  /** @internal */
+  notifyContent(content: string | null): void {
+    if (this._disposed)
+      return
+    this._content = content
+    for (const listener of this._contentListeners)
+      listener(content)
+  }
+
+  /** @internal */
+  dispose(): void {
+    if (this._disposed)
+      return
+    this._disposed = true
+    this._propsListeners.clear()
+    this._contentListeners.clear()
+  }
+
+  private _subscribeProps(listener: PropsListener<Props>, options?: SubscribeOptions): () => void {
+    if (this._disposed || options?.signal?.aborted)
+      return () => {}
+    // Add to the set BEFORE firing `immediate` so a re-entrant
+    // `notifyProps` triggered from inside the immediate callback can
+    // find this listener and fire it for the synchronous change too.
+    this._propsListeners.add(listener)
+    if (options?.immediate)
+      listener(this._props, this._errors)
+    const unsub = () => {
+      this._propsListeners.delete(listener)
+      // Manual unsub must also detach the abort listener — otherwise it
+      // accumulates on long-lived signals (e.g. an AbortController kept
+      // around for the element's whole lifetime that fans out to many
+      // subscriptions). `{ once: true }` only auto-removes when 'abort'
+      // actually fires.
+      options?.signal?.removeEventListener('abort', unsub)
+    }
+    options?.signal?.addEventListener('abort', unsub, { once: true })
+    return unsub
+  }
+
+  private _subscribeContent(listener: ContentListener, options?: SubscribeOptions): () => void {
+    if (this._disposed || options?.signal?.aborted)
+      return () => {}
+    this._contentListeners.add(listener)
+    if (options?.immediate)
+      listener(this._content)
+    const unsub = () => {
+      this._contentListeners.delete(listener)
+      options?.signal?.removeEventListener('abort', unsub)
+    }
+    options?.signal?.addEventListener('abort', unsub, { once: true })
+    return unsub
+  }
+}