@furystack/shades 11.1.0 → 12.0.1

package/src/components/router.tsx

@@ -1,12 +1,14 @@
 import { ObservableAlreadyDisposedError } from '@furystack/utils'
 import type { MatchOptions, MatchResult } from 'path-to-regexp'
 import { match } from 'path-to-regexp'
-import { Lock } from 'semaphore-async-await'
 import type { RenderOptions } from '../models/render-options.js'
 import { LocationService } from '../services/location-service.js'
 import { createComponent } from '../shade-component.js'
 import { Shade } from '../shade.js'
 
+/**
+ * @deprecated Use NestedRouter instead
+ */
 export interface Route<TMatchResult = unknown> {
   url: string
   component: (options: {
@@ -14,26 +16,36 @@ export interface Route<TMatchResult = unknown> {
     match: MatchResult<TMatchResult extends object ? TMatchResult : object>
   }) => JSX.Element
   routingOptions?: MatchOptions
-  onVisit?: (options: RenderOptions<unknown>) => Promise<void>
-  onLeave?: (options: RenderOptions<unknown>) => Promise<void>
+  onVisit?: (options: RenderOptions<unknown> & { element: JSX.Element }) => Promise<void>
+  onLeave?: (options: RenderOptions<unknown> & { element: JSX.Element }) => Promise<void>
 }
 
+/**
+ * @deprecated Use NestedRouterProps instead
+ */
 export interface RouterProps {
   style?: CSSStyleDeclaration
   routes: Array<Route<any>>
   notFound?: JSX.Element
 }
 
+/**
+ * @deprecated Use NestedRouterState instead
+ */
 export interface RouterState {
   activeRoute?: Route<unknown> | null
   activeRouteParams?: unknown
   jsx: JSX.Element
 }
+
+/**
+ * @deprecated Use NestedRouter instead
+ */
 export const Router = Shade<RouterProps>({
   shadowDomName: 'shade-router',
   render: (options) => {
     const { useState, useObservable, injector } = options
-    const [lock] = useState('lock', new Lock())
+    const [versionRef] = useState('navVersion', { current: 0 })
     const [state, setState] = useState<RouterState>('routerState', {
       jsx: <div />,
     })
@@ -42,23 +54,27 @@ export const Router = Shade<RouterProps>({
       const [lastState] = useState<RouterState>('routerState', state)
       const { activeRoute: lastRoute, activeRouteParams: lastRouteParams, jsx: lastJsx } = lastState
       try {
-        await lock.acquire()
         for (const route of options.props.routes) {
           const matchFn = match(route.url, route.routingOptions)
           const matchResult = matchFn(currentUrl)
           if (matchResult) {
             if (route !== lastRoute || JSON.stringify(lastRouteParams) !== JSON.stringify(matchResult.params)) {
+              const version = ++versionRef.current
               await lastRoute?.onLeave?.({ ...options, element: lastState.jsx })
+              if (version !== versionRef.current) return
               const newJsx = route.component({ currentUrl, match: matchResult })
               setState({ jsx: newJsx, activeRoute: route, activeRouteParams: matchResult.params })
               await route.onVisit?.({ ...options, element: newJsx })
+              if (version !== versionRef.current) return
             }
             return
           }
         }
 
         if (lastRoute !== null) {
+          const version = ++versionRef.current
           await lastRoute?.onLeave?.({ ...options, element: lastJsx })
+          if (version !== versionRef.current) return
           setState({
             jsx: options.props.notFound || <div />,
             activeRoute: null,
@@ -66,12 +82,9 @@ export const Router = Shade<RouterProps>({
           })
         }
       } catch (e) {
-        // path updates can be async, this can be ignored
         if (!(e instanceof ObservableAlreadyDisposedError)) {
           throw e
         }
-      } finally {
-        lock?.release()
       }
     }
 

package/src/initialize.ts

@@ -1,10 +1,22 @@
 import type { Injector } from '@furystack/inject'
 
+/**
+ * Options for bootstrapping a Shades application.
+ */
 export interface InitializeOptions {
+  /** The DOM element that will host the application */
   rootElement: HTMLElement
+  /** The root JSX element to render */
   jsxElement: JSX.Element
+  /** The root injector instance for dependency injection */
   injector: Injector
 }
+
+/**
+ * Bootstraps a Shades application by attaching the root JSX element to a DOM node
+ * and wiring up the dependency injection context.
+ * @param options The initialization options
+ */
 export const initializeShadeRoot = (options: InitializeOptions) => {
   options.jsxElement.injector = options.injector
   options.rootElement.appendChild(options.jsxElement)

package/src/jsx.ts

@@ -1,6 +1,48 @@
 import type { Injector } from '@furystack/inject'
 import type { ChildrenList, PartialElement } from './models/index.js'
 import type { ResourceManager } from './services/resource-manager.js'
+import type {
+  SvgAnimateAttributes,
+  SvgAnimateMotionAttributes,
+  SvgAnimateTransformAttributes,
+  SvgCircleAttributes,
+  SvgClipPathAttributes,
+  SvgCoreAttributes,
+  SvgDefsAttributes,
+  SvgDescAttributes,
+  SvgEllipseAttributes,
+  SvgFeBlendAttributes,
+  SvgFeColorMatrixAttributes,
+  SvgFeCompositeAttributes,
+  SvgFeFloodAttributes,
+  SvgFeGaussianBlurAttributes,
+  SvgFeMergeAttributes,
+  SvgFeMergeNodeAttributes,
+  SvgFeOffsetAttributes,
+  SvgFilterAttributes,
+  SvgForeignObjectAttributes,
+  SvgGAttributes,
+  SvgImageAttributes,
+  SvgLinearGradientAttributes,
+  SvgLineAttributes,
+  SvgMarkerAttributes,
+  SvgMaskAttributes,
+  SvgPathAttributes,
+  SvgPatternAttributes,
+  SvgPolygonAttributes,
+  SvgPolylineAttributes,
+  SvgRadialGradientAttributes,
+  SvgRectAttributes,
+  SvgSetAttributes,
+  SvgStopAttributes,
+  SvgSvgAttributes,
+  SvgSymbolAttributes,
+  SvgTextAttributes,
+  SvgTextPathAttributes,
+  SvgTitleAttributes,
+  SvgTspanAttributes,
+  SvgUseAttributes,
+} from './svg-types.js'
 
 declare global {
   // eslint-disable-next-line @typescript-eslint/no-namespace
@@ -10,7 +52,6 @@ declare global {
       props: TProps
       updateComponent: () => void
       shadeChildren?: ChildrenList
-      callConstructed: () => void
       resourceManager: ResourceManager
       getRenderCount(): number
     }
@@ -423,7 +464,7 @@ declare global {
        * The <svg> tag defines a container for SVG graphics.
        * SVG has several methods for drawing paths, boxes, circles, text, and graphic images.
        */
-      svg: PartialElement<SVGElement>
+      svg: SvgSvgAttributes
       /**
        * The <table> tag defines an HTML table.
        * An HTML table consists of the <table> element and one or more <tr>, <th>, and <td> elements.
@@ -519,6 +560,92 @@ declare global {
        * Tip: When a word is too long, or you are afraid that the browser will break your lines at the wrong place, you can use the <wbr> element to add word break opportunities.
        */
       wbr: PartialElement<HTMLElement>
+
+      // -------------------------------------------------------------------
+      // SVG Elements
+      // -------------------------------------------------------------------
+
+      /** The `<g>` element groups SVG elements together. */
+      g: SvgGAttributes
+      /** The `<defs>` element stores graphical objects for later reuse. */
+      defs: SvgDefsAttributes
+      /** The `<symbol>` element defines a reusable graphical template. */
+      symbol: SvgSymbolAttributes
+      /** The `<use>` element references another element for rendering. */
+      use: SvgUseAttributes
+      /** The `<path>` element defines a shape via SVG path commands. */
+      path: SvgPathAttributes
+      /** The `<rect>` element draws a rectangle. */
+      rect: SvgRectAttributes
+      /** The `<circle>` element draws a circle. */
+      circle: SvgCircleAttributes
+      /** The `<ellipse>` element draws an ellipse. */
+      ellipse: SvgEllipseAttributes
+      /** The `<line>` element draws a straight line between two points. */
+      line: SvgLineAttributes
+      /** The `<polyline>` element draws connected straight line segments. */
+      polyline: SvgPolylineAttributes
+      /** The `<polygon>` element draws a closed shape of connected line segments. */
+      polygon: SvgPolygonAttributes
+      /** The `<text>` element renders text in SVG. */
+      text: SvgTextAttributes
+      /** The `<tspan>` element defines a subtext within a `<text>` element. */
+      tspan: SvgTspanAttributes
+      /** The `<textPath>` element renders text along a path. */
+      textPath: SvgTextPathAttributes
+      /** The `<clipPath>` element defines a clipping region. */
+      clipPath: SvgClipPathAttributes
+      /** The `<mask>` element defines an alpha mask for compositing. */
+      mask: SvgMaskAttributes
+      /** The `<linearGradient>` element defines a linear color gradient. */
+      linearGradient: SvgLinearGradientAttributes
+      /** The `<radialGradient>` element defines a radial color gradient. */
+      radialGradient: SvgRadialGradientAttributes
+      /** The `<stop>` element defines a color stop in a gradient. */
+      stop: SvgStopAttributes
+      /** The `<pattern>` element defines a repeating graphic pattern. */
+      pattern: SvgPatternAttributes
+      /** The `<marker>` element defines a graphic for drawing on edges of shapes. */
+      marker: SvgMarkerAttributes
+      /** The `<filter>` element defines a set of filter operations. */
+      filter: SvgFilterAttributes
+      /** The `<feGaussianBlur>` filter primitive blurs the input image. */
+      feGaussianBlur: SvgFeGaussianBlurAttributes
+      /** The `<feBlend>` filter primitive composites two inputs. */
+      feBlend: SvgFeBlendAttributes
+      /** The `<feColorMatrix>` filter primitive applies a matrix color transform. */
+      feColorMatrix: SvgFeColorMatrixAttributes
+      /** The `<feOffset>` filter primitive offsets the input image. */
+      feOffset: SvgFeOffsetAttributes
+      /** The `<feFlood>` filter primitive fills with a solid color. */
+      feFlood: SvgFeFloodAttributes
+      /** The `<feMerge>` filter primitive composites multiple inputs. */
+      feMerge: SvgFeMergeAttributes
+      /** The `<feMergeNode>` element defines an input for `<feMerge>`. */
+      feMergeNode: SvgFeMergeNodeAttributes
+      /** The `<feComposite>` filter primitive combines images using Porter-Duff operations. */
+      feComposite: SvgFeCompositeAttributes
+      /** The `<image>` element (SVG) embeds a raster image. */
+      image: SvgImageAttributes
+      /** The `<foreignObject>` element embeds external XML (e.g. HTML) in SVG. */
+      foreignObject: SvgForeignObjectAttributes
+      /** The `<animate>` element animates an attribute over time. */
+      animate: SvgAnimateAttributes
+      /** The `<animateMotion>` element animates an element along a path. */
+      animateMotion: SvgAnimateMotionAttributes
+      /** The `<animateTransform>` element animates a transformation attribute. */
+      animateTransform: SvgAnimateTransformAttributes
+      /** The `<set>` element sets an attribute to a value for a duration. */
+      set: SvgSetAttributes
+      /** The `<title>` element (SVG) provides an accessible title. */
+      title: SvgTitleAttributes
+      /** The `<desc>` element provides an accessible description. */
+      desc: SvgDescAttributes
+      /**
+       * Catch-all for SVG filter primitives and other SVG elements
+       * not explicitly listed above.
+       */
+      [key: `fe${string}`]: SvgCoreAttributes
     }
   }
 }

package/src/models/children-list.ts

@@ -1 +1,7 @@
-export type ChildrenList = Array<string | HTMLElement | JSX.Element | string[] | HTMLElement[] | JSX.Element[]>
+/**
+ * The type for children passed to Shade components and intrinsic JSX elements.
+ * Supports strings, HTML/SVG elements, JSX elements, and nested arrays of these.
+ */
+export type ChildrenList = Array<
+  string | HTMLElement | SVGElement | JSX.Element | string[] | HTMLElement[] | SVGElement[] | JSX.Element[]
+>

package/src/models/partial-element.ts

@@ -1,5 +1,16 @@
-export type PartialElement<T> = T extends { style?: CSSStyleDeclaration }
+import type { RefObject } from './render-options.js'
+
+/**
+ * Makes all properties of an HTML element type optional, with `style` narrowed
+ * to `Partial<CSSStyleDeclaration>` and a `ref` prop for capturing DOM references.
+ * Used as the props type for intrinsic JSX elements and component host element overrides.
+ * @typeParam T - The base HTML element type
+ */
+export type PartialElement<T> = (T extends { style?: CSSStyleDeclaration }
   ? Omit<Partial<T>, 'style'> & {
       style?: Partial<CSSStyleDeclaration>
     }
-  : Partial<T>
+  : Partial<T>) & {
+  /** Ref object to capture a reference to the underlying DOM element. */
+  ref?: RefObject<Element>
+}

package/src/models/render-options.ts

@@ -3,12 +3,81 @@ import type { ObservableValue, ValueObserverOptions } from '@furystack/utils'
 import type { ChildrenList } from './children-list.js'
 import type { PartialElement } from './partial-element.js'
 
+/**
+ * A reference object returned by `useRef`.
+ * `current` is set to the DOM element when it is mounted, and `null` when unmounted.
+ * The `readonly` modifier ensures covariance so that `RefObject<HTMLInputElement>`
+ * is assignable to `RefObject<Element>`.
+ */
+export type RefObject<T extends Element = HTMLElement> = {
+  readonly current: T | null
+}
+
+/**
+ * Options provided to a Shade component's `render` function.
+ * Contains the current props, injector, children, and hooks for managing state, side effects, and host element attributes.
+ * @typeParam TProps - The component's props type
+ * @typeParam TElementBase - The base HTML element type (defaults to HTMLElement)
+ */
 export type RenderOptions<TProps, TElementBase extends HTMLElement = HTMLElement> = {
   readonly props: TProps & PartialElement<TElementBase>
   renderCount: number
   injector: Injector
   children?: ChildrenList
-  element: JSX.Element<TProps>
+  /**
+   * Declaratively sets attributes and styles on the host custom element.
+   * Can be called multiple times per render; each call merges into the previous values.
+   *
+   * CSS custom properties (e.g. `--my-color`) are applied via `setProperty`.
+   * The `style` property accepts both standard camelCase properties and CSS custom properties.
+   *
+   * **Best practice:** Use `useHostProps` for data attributes, ARIA attributes, CSS variables,
+   * and event handlers on the host element instead of imperative DOM manipulation.
+   *
+   * @param hostProps An object of attribute key-value pairs, optionally including a `style` record
+   *
+   * **Note:** Object and function values are assigned as properties on the host element
+   * (not as attributes). This means you can set event handlers (e.g. `onclick`) and
+   * even class properties like `injector` via `useHostProps`.
+   *
+   * @example
+   * ```typescript
+   * useHostProps({
+   *   'data-variant': props.variant,
+   *   role: 'progressbar',
+   *   'aria-valuenow': String(value),
+   *   style: {
+   *     '--btn-color-main': colors.main,
+   *     display: 'flex',
+   *   },
+   * })
+   * ```
+   */
+  useHostProps: (hostProps: Record<string, unknown> & { style?: Record<string, string> }) => void
+
+  /**
+   * Creates a mutable ref object that can be attached to intrinsic JSX elements via the `ref` prop.
+   * The ref's `current` property will be set to the DOM element after mount and `null` on unmount.
+   *
+   * Refs are cached by key, so calling `useRef` with the same key returns the same object across renders.
+   *
+   * **Best practice:** Prefer declarative JSX and `useHostProps` when possible.
+   * Use refs sparingly for imperative needs like focus management or measuring elements.
+   *
+   * @param key A unique key for caching the ref object
+   * @returns A ref object with a `current` property
+   *
+   * @example
+   * ```typescript
+   * const inputRef = useRef<HTMLInputElement>('input')
+   * // In JSX:
+   * <input ref={inputRef} />
+   * // Later:
+   * inputRef.current?.focus()
+   * ```
+   */
+  useRef: <T extends Element = HTMLElement>(key: string) => RefObject<T>
+
   /**
    * Creates and disposes a resource after the component has been detached from the DOM
    * @param key The key for caching the disposable resource
@@ -18,11 +87,29 @@ export type RenderOptions<TProps, TElementBase extends HTMLElement = HTMLElement
   useDisposable: <T extends Disposable | AsyncDisposable>(key: string, factory: () => T) => T
 
   /**
-   * Creates a state object from an existing observable value
+   * Creates a state object from an existing observable value.
+   *
+   * **Important:** By default, this will trigger a full component re-render when the observable value changes.
+   * To prevent re-renders (e.g., for manual DOM updates or animations), provide a custom `onChange` callback.
+   *
    * @param key The key for caching the observable value
    * @param observable The observable value to observe
-   * @param options Optional options for the observer including onChange callback
+   * @param options Optional options for the observer
+   * @param options.onChange Custom callback when value changes. If not provided, the component will re-render on each change.
    * @returns tuple with the current value and a setter function
+   *
+   * @example
+   * // Default behavior: re-renders component on change
+   * const [count] = useObservable('count', countObservable)
+   *
+   * @example
+   * // Custom onChange: no re-render, update host element via useHostProps
+   * useHostProps({ 'data-active': count > 0 ? '' : undefined })
+   * const [count] = useObservable('count', countObservable, {
+   *   onChange: () => {
+   *     // Triggers a re-render so useHostProps above picks up the new value
+   *   }
+   * })
    */
   useObservable: <T>(
     key: string,

package/src/models/selection-state.ts

@@ -1,3 +1,7 @@
+/**
+ * Captures the current focus and selection range within a DOM subtree.
+ * Used internally by the reconciler to preserve user selection across re-renders.
+ */
 export interface SelectionState {
   focusedPath?: number[]
   selectionRange?: {

package/src/services/location-service.tsx

@@ -4,6 +4,10 @@ import {
   serializeToQueryString as defaultSerializeToQueryString,
 } from '@furystack/rest'
 import { ObservableValue } from '@furystack/utils'
+/**
+ * Singleton service that tracks browser location changes (pathname, search, hash)
+ * and exposes them as observable values for reactive routing and URL-driven state.
+ */
 @Injectable({ lifetime: 'singleton' })
 export class LocationService implements Disposable {
   constructor(
@@ -119,6 +123,13 @@ export class LocationService implements Disposable {
   }).bind(this)
 }
 
+/**
+ * Configures custom serialization for URL search state.
+ * Must be called **before** `LocationService` is first instantiated by the injector.
+ * @param injector The root injector
+ * @param serialize Function to serialize state to a query string
+ * @param deserialize Function to deserialize a query string to state
+ */
 export const useCustomSearchStateSerializer = (
   injector: Injector,
   serialize: typeof defaultSerializeToQueryString,

package/src/services/resource-manager.spec.ts

@@ -19,6 +19,122 @@ describe('ResourceManager', () => {
     })
   })
 
+  it('Should switch to a new observable when a different reference is passed for the same key', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o1 = new ObservableValue(1)
+      const o2 = new ObservableValue(42)
+      const onChange = vi.fn()
+
+      const [value1] = rm.useObservable('test', o1, onChange)
+      expect(value1).toBe(1)
+      expect(o1.getObservers().length).toBe(1)
+
+      const [value2] = rm.useObservable('test', o2, onChange)
+      expect(value2).toBe(42)
+      expect(o1.getObservers().length).toBe(0)
+      expect(o2.getObservers().length).toBe(1)
+    })
+  })
+
+  it('Should subscribe with the new onChange callback when switching observables', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o1 = new ObservableValue('a')
+      const o2 = new ObservableValue('x')
+      const onChange1 = vi.fn()
+      const onChange2 = vi.fn()
+
+      rm.useObservable('test', o1, onChange1)
+      rm.useObservable('test', o2, onChange2)
+
+      o2.setValue('y')
+      expect(onChange2).toHaveBeenCalledWith('y')
+      expect(onChange1).not.toHaveBeenCalled()
+    })
+  })
+
+  it('Should not re-subscribe when the same observable reference is passed', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o = new ObservableValue(1)
+      const onChange = vi.fn()
+
+      rm.useObservable('test', o, onChange)
+      rm.useObservable('test', o, onChange)
+      rm.useObservable('test', o, onChange)
+
+      expect(o.getObservers().length).toBe(1)
+    })
+  })
+
+  it('Should return a setValue bound to the new observable after switching', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o1 = new ObservableValue(1)
+      const o2 = new ObservableValue(10)
+      const onChange = vi.fn()
+
+      const [, setValue1] = rm.useObservable('test', o1, onChange)
+      setValue1(5)
+      expect(o1.getValue()).toBe(5)
+
+      const [, setValue2] = rm.useObservable('test', o2, onChange)
+      setValue2(99)
+      expect(o2.getValue()).toBe(99)
+      expect(o1.getValue()).toBe(5)
+    })
+  })
+
+  it('Should handle multiple sequential observable switches for the same key', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o1 = new ObservableValue('a')
+      const o2 = new ObservableValue('b')
+      const o3 = new ObservableValue('c')
+      const onChange = vi.fn()
+
+      const [v1] = rm.useObservable('test', o1, onChange)
+      expect(v1).toBe('a')
+
+      const [v2] = rm.useObservable('test', o2, onChange)
+      expect(v2).toBe('b')
+      expect(o1.getObservers().length).toBe(0)
+
+      const [v3] = rm.useObservable('test', o3, onChange)
+      expect(v3).toBe('c')
+      expect(o2.getObservers().length).toBe(0)
+      expect(o3.getObservers().length).toBe(1)
+    })
+  })
+
+  it('Should not trigger callbacks on the old observable after switching', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o1 = new ObservableValue(1)
+      const o2 = new ObservableValue(2)
+      const onChange = vi.fn()
+
+      rm.useObservable('test', o1, onChange)
+      rm.useObservable('test', o2, onChange)
+
+      onChange.mockClear()
+      o1.setValue(999)
+      expect(onChange).not.toHaveBeenCalled()
+
+      o2.setValue(100)
+      expect(onChange).toHaveBeenCalledWith(100)
+    })
+  })
+
+  it('Should clean up switched observers on dispose', async () => {
+    const o1 = new ObservableValue(1)
+    const o2 = new ObservableValue(2)
+    const onChange = vi.fn()
+
+    await usingAsync(new ResourceManager(), async (rm) => {
+      rm.useObservable('test', o1, onChange)
+      rm.useObservable('test', o2, onChange)
+      expect(o2.getObservers().length).toBe(1)
+    })
+
+    expect(o2.getObservers().length).toBe(0)
+  })
+
   it('Should return a disposable from cache', async () => {
     await usingAsync(new ResourceManager(), async (rm) => {
       const factory = vi.fn(() => ({
@@ -80,6 +196,18 @@ describe('ResourceManager', () => {
     expect(disposable[Symbol.dispose]).toHaveBeenCalledTimes(1)
   })
 
+  it('Should silently ignore useState setter calls after disposal', async () => {
+    let setValueFn: (value: number) => void
+
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const [, setValue] = rm.useState<number>('count', 0, vi.fn())
+      setValueFn = setValue
+    })
+
+    // After disposal, calling the setter should not throw
+    expect(() => setValueFn!(42)).not.toThrow()
+  })
+
   it('Should throw an aggregated error when failed to async dispose something', async () => {
     const disposable = {
       [Symbol.asyncDispose]: vi.fn(async () => {

package/src/services/resource-manager.ts

@@ -8,6 +8,13 @@ import { ObservableValue, isAsyncDisposable, isDisposable } from '@furystack/uti
 export class ResourceManager implements AsyncDisposable {
   private readonly disposables = new Map<string, Disposable | AsyncDisposable>()
 
+  /**
+   * Returns an existing disposable resource by key, or creates and caches a new one.
+   * Resources are automatically disposed when the component is removed from the DOM.
+   * @param key Unique key for caching this resource
+   * @param factory Factory function called once to create the resource
+   * @returns The cached or newly created resource
+   */
   public useDisposable<T extends Disposable | AsyncDisposable>(key: string, factory: () => T): T {
     const existing = this.disposables.get(key)
     if (!existing) {
@@ -20,6 +27,15 @@ export class ResourceManager implements AsyncDisposable {
 
   public readonly observers = new Map<string, ValueObserver<any>>()
 
+  /**
+   * Subscribes to an observable value by key. If the observable changes between renders,
+   * the previous subscription is disposed and a new one is created.
+   * @param key Unique key for caching this subscription
+   * @param observable The observable to subscribe to
+   * @param onChange Callback invoked when the value changes
+   * @param options Additional observer options
+   * @returns Tuple of [currentValue, setValue]
+   */
   public useObservable = <T>(
     key: string,
     observable: ObservableValue<T>,
@@ -28,6 +44,12 @@ export class ResourceManager implements AsyncDisposable {
   ): [value: T, setValue: (newValue: T) => void] => {
     const alreadyUsed = this.observers.get(key) as ValueObserver<T> | undefined
     if (alreadyUsed) {
+      if (alreadyUsed.observable !== observable) {
+        alreadyUsed[Symbol.dispose]()
+        const observer = observable.subscribe(onChange, options)
+        this.observers.set(key, observer)
+        return [observable.getValue(), observable.setValue.bind(observable)]
+      }
       return [alreadyUsed.observable.getValue(), alreadyUsed.observable.setValue.bind(alreadyUsed.observable)]
     }
     const observer = observable.subscribe(onChange, options)
@@ -37,6 +59,14 @@ export class ResourceManager implements AsyncDisposable {
 
   public readonly stateObservers = new Map<string, ObservableValue<any>>()
 
+  /**
+   * Creates or retrieves a local state observable by key.
+   * State is persisted across re-renders and disposed with the component.
+   * @param key Unique key for caching this state
+   * @param initialValue Initial value used on first call
+   * @param callback Callback invoked when the state changes
+   * @returns Tuple of [currentValue, setValue]
+   */
   public useState = <T>(
     key: string,
     initialValue: T,
@@ -48,7 +78,12 @@ export class ResourceManager implements AsyncDisposable {
       newObservable.subscribe(callback)
     }
     const observable = this.stateObservers.get(key) as ObservableValue<T>
-    return [observable.getValue(), observable.setValue.bind(observable)]
+    const setValue = (newValue: T) => {
+      if (!observable.isDisposed) {
+        observable.setValue(newValue)
+      }
+    }
+    return [observable.getValue(), setValue]
   }
 
   public async [Symbol.asyncDispose]() {