@sprucelabs/spruce-heartwood-utils 38.16.1 → 38.16.2

package/README.md

@@ -1,240 +1,1157 @@
-<img src="./docs/images/hero.jpg">
+# @sprucelabs/spruce-heartwood-utils
 
-# Heartwood Skill
+Tools for building Spruce skills that integrate with Heartwood — remote card loading, auto-logout control, animation primitives, and testing utilities.
 
-[![AI TDD Contributor](https://regressionproof.ai/badge.svg)](https://regressionproof.ai)
+---
 
-The core UI framework and skill for the Spruce Experience Platform. Heartwood provides the view controller architecture, component library, theming system, and Storybook integration that powers all Spruce skills.
+## Table of Contents
 
-## Overview
+1. [Remote View Controllers](#remote-view-controllers)
+2. [CardRegistrar](#cardregistrar)
+3. [Types](#types)
+4. [Theming](#theming)
+5. [Plugins](#plugins)
+6. [Test Utilities](#test-utilities)
+7. [Device & Layout Utilities](#device--layout-utilities)
+8. [Animation](#animation)
+   - [Quick Start](#quick-start)
+   - [Required CSS](#required-css)
+   - [System Architecture](#system-architecture)
+   - [AnimationEmitter](#animationemitter)
+   - [Settings](#settings)
+   - [queueShow — Show/Hide Queue](#queueshow--showhide-queue)
+   - [Sizer — Animated Height Container](#sizer--animated-height-container)
+   - [DelayedPlacer — Absolute Positioning](#delayedplacer--absolute-positioning)
+   - [sizeUtil — DOM Measurement](#sizeutil--dom-measurement)
+   - [How the Three Systems Coordinate](#how-the-three-systems-coordinate)
 
-Heartwood serves as:
-- **The primary UI layer** for Spruce XP
-- **A view controller framework** built on `@sprucelabs/heartwood-view-controllers`
-- **A skill management platform** that registers, loads, and serves view controllers dynamically
-- **A comprehensive component library** with 40+ UI components
+---
 
-## Features
+## Remote View Controllers
 
-### View Controllers
+When your skill needs to load and render cards that come from other skills at runtime, these are the types you work with. In tests, you swap in `MockRemoteViewControllerFactory` to control which cards appear without making real network calls.
 
-Heartwood uses a controller-based architecture for building UIs...
+### `RemoteViewControllerFactoryImpl`
 
-```typescript
-class MySkillViewController extends AbstractSkillViewController {
-    private cardVc: CardViewController
+Fetches compiled ViewController source from the `heartwood.get-skill-views` event, evaluates it in a sandboxed context, and returns instantiated controllers. You will typically interact with this class in tests to inject a mock, not to instantiate it in production — Heartwood manages the factory lifecycle.
 
-    constructor(options: ViewControllerOptions) {
-        super(options)
-        this.cardVc = this.Controller('card', {
-            header: { title: 'Welcome' },
-            body: { items: [{ text: 'Hello World' }] }
-        })
-    }
+```ts
+import {
+    RemoteViewControllerFactoryImpl,
+    RemoteViewControllerFactory,
+} from '@sprucelabs/spruce-heartwood-utils'
+```
 
-    render(): SkillView {
-        return {
-            layouts: [buildSkillViewLayout('one-col', {
-                cards: [this.cardVc.render()]
-            })]
-        }
-    }
+**Injecting a mock factory in tests:**
+
+```ts
+protected async beforeEach() {
+    RemoteViewControllerFactoryImpl.Class = MockRemoteViewControllerFactory
+    MockRemoteViewControllerFactory.reset()
+}
+```
+
+**Loading a remote controller by ID:**
+
+```ts
+const vc = await remoteVcFactory.RemoteController(
+    'your-skill.some-card',
+    { someOption: true }
+)
+```
+
+---
+
+### `RemoteViewControllerFactory` (interface)
+
+The interface that both `RemoteViewControllerFactoryImpl` and `MockRemoteViewControllerFactory` implement. Use this type for any field that may hold the real factory or a test mock:
+
+```ts
+import { RemoteViewControllerFactory } from '@sprucelabs/spruce-heartwood-utils'
+
+private remoteVcFactory: RemoteViewControllerFactory
+```
+
+---
+
+### `RemoteFactoryOptions`
+
+Options passed to `RemoteViewControllerFactoryImpl.Factory()`.
+
+```ts
+import { RemoteFactoryOptions } from '@sprucelabs/spruce-heartwood-utils'
+
+interface RemoteFactoryOptions {
+    connectToApi: () => Promise<MercuryClient>
+    vcFactory: VcFactoryForRemoteFactory
+}
+```
+
+---
+
+### `VcFactoryForRemoteFactory`
+
+A narrowed subset of `ViewControllerFactory` containing only what the remote factory needs. Use this type when accepting or storing a factory reference to avoid a full `ViewControllerFactory` dependency:
+
+```ts
+import { VcFactoryForRemoteFactory } from '@sprucelabs/spruce-heartwood-utils'
+
+private views: VcFactoryForRemoteFactory
+```
+
+---
+
+## CardRegistrar
+
+If your skill view needs to collect cards contributed by other skills — similar to a dashboard that aggregates content from across the platform — `CardRegistrar` handles the full lifecycle: emitting the event, receiving VC IDs from respondents, loading each card via the remote factory, and streaming results as they arrive.
+
+```ts
+import {
+    CardRegistrar,
+    CardRegistrarOptions,
+    CardFetchOptions,
+    EachCardHandler,
+} from '@sprucelabs/spruce-heartwood-utils'
+```
+
+### `CardRegistrar.Registrar(options)`
+
+Create a fresh registrar inside your skill view's `load()` so each load cycle gets a fresh client connection:
+
+```ts
+private async loadContributedCards(options: SkillViewControllerLoadOptions) {
+    const client = await this.connectToApi()
+
+    const registrar = CardRegistrar.Registrar({
+        client,
+        eventName: 'your-skill.register-cards::v2021_02_11',
+        vcFactory: this.getVcFactory(),
+        vcIdsTransformer: (payload) => payload.vcIds,
+    })
+
+    this.remoteCards = (await registrar.fetch()) as RemoteDashboardCard[]
+    this.triggerRender()
+
+    await Promise.all(this.remoteCards.map((vc) => vc.load?.(options)))
+}
+```
+
+### `CardRegistrarOptions<Contract, Name>`
+
+```ts
+interface CardRegistrarOptions<Contract, Name> {
+    client: MercuryClient
+    eventName: Name
+    vcFactory: VcFactoryForRemoteFactory
+    vcIdsTransformer: (payload: ResponsePayload<Contract, Name>) => string[]
 }
 ```
 
-**Built-in View Controllers:**
-- `heartwood.root` - Main dashboard
-- `heartwood.loading` - Loading states
-- `heartwood.error` - Error display
-- `heartwood.not-found` - 404 handling
-- `heartwood.scope-tool` - Organization/location scope management
-
-### Storybook Integration
-
-Heartwood includes comprehensive Storybook support for component development and documentation:
-
-```bash
-# Start Storybook dev server
-yarn storybook
-
-# Build static Storybook
-yarn build-storybook
-```
-
-**44+ Story Categories:**
-- UI Components: buttons, cards, dialogs, forms, icons, dropdowns
-- Data Display: lists, tables, feeds, timelines
-- Navigation: pager, tabs, progress navigation
-- Calendars: day view, month view, event management
-- Charts: bar, line, polar area (via Chart.js)
-- Maps: location display and selection
-- Advanced: conferencing, streaming, swipe interactions
-
-Stories use the same view controller pattern as production code, making them excellent for testing and documentation.
-
-### Events
-
-**Skill Events:**
-
-| Event | Description |
-|-------|-------------|
-| `heartwood.register-skill-views` | Register view controllers from other skills |
-| `heartwood.get-skill-views` | Fetch registered views by namespace |
-| `heartwood.list-views` | List all registered skill views |
-| `heartwood.did-register-skill-views` | Notification after registration complete |
-| `heartwood.upsert-theme` | Update skill theme |
-| `heartwood.get-active-theme` | Get current theme |
-
-**UI Events (SkillViewEmitter):**
-
-| Event | Description |
-|-------|-------------|
-| `did-change-orientation` | Device orientation changed |
-| `did-resize` | Window resized |
-| `did-render` | View rendered |
-| `will-change-route` | Before navigation |
-| `did-render-dialog` | Dialog displayed |
-| `did-keydown` | Keyboard input |
-| `did-scroll` | Page scrolled |
-| `connection-status-changed` | Mercury connection status |
-
-### Component Library
-
-**Forms (32+ field types):**
-- Text, textarea, phone, email
-- Select, checkbox, toggle
-- Date, time, datetime, duration
-- Address, ratings, color picker
-- File upload, signature capture
-
-**Layout Components:**
-- Cards with headers, bodies, footers
-- Grid layouts (one-col, two-col, big-left, big-right)
-- Dialogs and modals
-- Slide panels
-- Tabs and accordions
-
-**Data Components:**
-- Lists with pagination
-- Tables with sorting
-- Feeds and activity streams
-- Progress indicators
-
-**Interactive Components:**
-- Buttons and button groups
-- Dropdowns and menus
-- Calendars and date pickers
-- Maps and location pickers
-- Charts and graphs
-
-### Theming
-
-Heartwood supports per-namespace theming:
-
-```typescript
-// Apply theme programmatically
-themeManager.setTheme({
-    name: 'My Theme',
-    colors: {
-        primary: '#00f0ff',
-        secondary: '#7b2fff'
+### `registrar.fetch(options?)`
+
+Emits the event and loads all returned VC IDs. Returns `AbstractViewController<Card>[]`.
+
+```ts
+// Basic fetch — wait for all cards
+const cards = await registrar.fetch()
+
+// Streaming — render each batch as it arrives
+await registrar.fetch({
+    each: async (batch) => {
+        this.remoteCards.push(...(batch as RemoteDashboardCard[]))
+        this.triggerRender()
     },
-    fonts: { ... },
-    borderRadius: '8px'
 })
+
+// With target — scope the event to an organization
+const cards = await registrar.fetch({
+    target: { organizationId: 'org-123' },
+})
+```
+
+### `EachCardHandler`
+
+```ts
+type EachCardHandler = (vcs: AbstractViewController<any>[]) => Promise<void> | void
+```
+
+### `CardFetchOptions<Contract, Name>`
+
+```ts
+type CardFetchOptions<Contract, Name> = {
+    each?: EachCardHandler
+    controllerOptionsHandler?: (vcId: string) => Record<string, any>
+} & EmitPayload<Contract, Name>
 ```
 
-Themes control: colors, fonts, card styles, border radius, calendar event colors, and more.
+---
 
-### Navigation
+## Types
 
-Hash-based routing system:
+### `RemoteDashboardCard`
 
-```typescript
-// Navigate to a view
-this.Router().redirect('my-skill.profile', { userId: '123' })
+The shape of a card loaded from another skill. Extends `ViewController<Card>` with an optional `load()` method so you can forward load arguments after the card is rendered.
 
-// URL format: #views/my-skill.profile?userId=123
+```ts
+import { RemoteDashboardCard } from '@sprucelabs/spruce-heartwood-utils'
+
+interface RemoteDashboardCard extends ViewController<Card> {
+    load?(options: SkillViewControllerLoadOptions): Promise<void>
+}
 ```
 
-Features:
-- View stack for back/forward navigation
-- Route restrictions for protected views
-- Deep linking support
+**Typical pattern — store, render, and forward load args:**
 
-### Authentication & Authorization
+```ts
+private remoteCards: RemoteDashboardCard[] = []
 
-```typescript
-// Check login status
-const isLoggedIn = this.getAuthenticator().isLoggedIn()
+// After fetch:
+this.remoteCards = (await registrar.fetch()) as RemoteDashboardCard[]
+await Promise.all(this.remoteCards.map((vc) => vc.load?.(options)))
 
-// Check permissions
-const canEdit = await this.getAuthorizer().can({
-    contractId: 'my-skill',
-    permissionIds: ['can-edit-profile']
-})
+// In render():
+cards: [
+    this.myLocalCardVc.render(),
+    ...this.remoteCards.map((c) => c.render()),
+]
+```
+
+---
+
+## Theming
+
+### `loadActiveThemeForOrg(client, organizationId)`
+
+Fetches the active Heartwood theme for an organization so your skill can apply the same visual style.
+
+```ts
+import { loadActiveThemeForOrg } from '@sprucelabs/spruce-heartwood-utils'
+```
+
+**Signature:**
+
+```ts
+async function loadActiveThemeForOrg(
+    client: MercuryClient,
+    organizationId: string
+): Promise<SkillTheme>
+```
+
+**Usage:**
+
+```ts
+const client = await this.connectToApi()
+const theme = await loadActiveThemeForOrg(client, organizationId)
+// pass theme to your view controller factory or apply to the UI
+```
+
+---
+
+## Plugins
+
+### `AutoLogoutPlugin`
+
+Sends `enableAutoLogout` / `disableAutoLogout` commands to the native Heartwood device layer. Register it with your skill's `ViewControllerFactory` to give your skill views control over session timeout behavior.
+
+```ts
+import { AutoLogoutPlugin } from '@sprucelabs/spruce-heartwood-utils'
+
+const plugin = factory.BuildPlugin(AutoLogoutPlugin)
+
+plugin.enableAutoLogout(300)   // auto-logout after 300 seconds of inactivity
+plugin.disableAutoLogout()     // cancel a pending auto-logout
 ```
 
-### Scope System
+---
 
-Manage organization/location context:
+### `AutoLogoutViewPlugin` (interface)
 
-```typescript
-// Get current scope
-const { organizationId, locationId } = this.getScope()
+Use this type when you want to reference the plugin without coupling to the concrete class — for example, when declaring a field that holds either the real plugin or a spy:
 
-// Scope selection UI
-this.Controller('heartwood.scope-selection-card', { ... })
+```ts
+import { AutoLogoutViewPlugin } from '@sprucelabs/spruce-heartwood-utils'
+
+interface AutoLogoutViewPlugin extends ViewControllerPlugin {
+    enableAutoLogout(durationSec: number): void
+    disableAutoLogout(): void
+}
 ```
 
-## Architecture
+---
+
+### `SpyAutoLogoutPlugin`
+
+A test double that records calls to `enableAutoLogout` and `disableAutoLogout`. Swap it in during test setup to assert your skill calls the plugin correctly:
+
+```ts
+import { SpyAutoLogoutPlugin } from '@sprucelabs/spruce-heartwood-utils'
 
+protected async beforeEach() {
+    const factory = this.views.getFactory()
+    factory.setPlugin('auto-logout', new SpyAutoLogoutPlugin())
+}
+
+@test()
+protected async startsAutoLogoutAfterLoad() {
+    await this.load()
+    assert.isTrue(this.plugin.wasEnableAutoLogoutCalled)
+    assert.isEqual(this.plugin.durationSec, 300)
+}
+
+private get plugin() {
+    return this.views.getFactory().getPlugin('auto-logout') as SpyAutoLogoutPlugin
+}
 ```
-App (React)
-├── AppEngine (Core runtime)
-│   ├── ViewControllerFactory
-│   ├── Router
-│   ├── Authenticator
-│   ├── ThemeManager
-│   └── RemoteViewControllerFactory
-├── SkillViewNavigator
-├── ControlBar (Navigation)
-└── Dialog System
+
+**Spy fields:**
+
+```ts
+class SpyAutoLogoutPlugin {
+    wasEnableAutoLogoutCalled: boolean
+    durationSec?: number
+    wasDisableAutoLogoutCalled: boolean
+}
 ```
 
-## Development
+---
+
+## Test Utilities
 
-```bash
-# Install dependencies
-yarn
+Use these in your skill's test suite to verify that your skill correctly registers cards with Heartwood and responds to dashboard events. The typical scenario: Heartwood emits an event asking for cards; your skill responds with VC IDs; Heartwood loads and renders those cards. These utilities let you assert that entire flow without making real network calls.
 
-# Build
-yarn build.dev
+### `remoteVcAssert`
 
-# Run tests
-yarn test
+High-level assertion helper. Verifies that your skill view emits the expected registration event and that the returned cards are rendered.
 
-# Start Storybook
-yarn storybook
+```ts
+import { remoteVcAssert } from '@sprucelabs/spruce-heartwood-utils'
+```
+
+**Basic assertion — confirm your skill view emits the event and renders cards:**
 
-# Build for CDN
-yarn build.cdn
+```ts
+@test()
+protected async registersCards() {
+    await remoteVcAssert.assertSkillViewRendersRemoteCards({
+        svc: this.vc,
+        fqen: 'your-skill.register-cards::v2021_02_11',
+        views: this.views,
+    })
+}
 ```
 
-## Registering Skill Views
+**With `shouldInvoke` — confirm each returned card has `load()` called on it:**
 
-Other skills register their view controllers with Heartwood:
+```ts
+await remoteVcAssert.assertSkillViewRendersRemoteCards({
+    svc: this.vc,
+    fqen: 'your-skill.register-cards::v2021_02_11',
+    views: this.views,
+    shouldInvoke: {
+        methodName: 'load',
+        expectedParams: [this.views.getRouter().buildLoadOptions()],
+    },
+})
+```
 
-```typescript
-await client.emitAndFlattenResponses('heartwood.register-skill-views::v2021_02_11', {
-    target: { skillId: 'your-skill-id' },
-    payload: {
-        ids: ['root', 'profile', 'settings'],
-        source: compiledViewControllerCode
+**With `expectedTarget` / `expectedPayload` — confirm the event is scoped correctly:**
+
+```ts
+await remoteVcAssert.assertSkillViewRendersRemoteCards({
+    svc: this.vc,
+    fqen: 'your-skill.register-cards::v2021_02_11',
+    views: this.views,
+    expectedTarget: { organizationId: 'org-123' },
+})
+```
+
+---
+
+### `AssertRendersRemoteCardsOptions<Svc>`
+
+```ts
+import { AssertRendersRemoteCardsOptions } from '@sprucelabs/spruce-heartwood-utils'
+
+interface AssertRendersRemoteCardsOptions<Svc extends SkillViewController = SkillViewController> {
+    svc: Svc
+    fqen: EventNames
+    views: ViewFixture
+    expectedTarget?: Record<string, any>
+    expectedPayload?: Record<string, any>
+    loadArgs?: ArgsFromSvc<Svc>
+    shouldInvoke?: {
+        methodName: string
+        expectedParams?: any[]
     }
+}
+```
+
+---
+
+### `fakeGetViews`
+
+Intercepts `heartwood.get-skill-views::v2021_02_11` and returns stub ViewController source. Useful when you need manual control over what remote views are returned in a test — `remoteVcAssert` uses this internally, but you can call it directly for custom scenarios.
+
+```ts
+import { fakeGetViews } from '@sprucelabs/spruce-heartwood-utils'
+
+// Stub two remote views:
+await fakeGetViews.fakeGetViews(['your-skill.card-a', 'your-skill.card-b'])
+
+// Stub a view with a tracked method — stub exposes wasHit and passedParams:
+await fakeGetViews.fakeGetViews(['your-skill.card'], 'load')
+```
+
+> **Note:** The export is the `heartwoodEventFaker` object. Call it as `fakeGetViews.fakeGetViews(...)`.
+
+---
+
+### `MockRemoteViewControllerFactory`
+
+A drop-in replacement for the real remote factory. Controls exactly which VC classes are returned for each card ID and provides assertion methods for verifying what your skill view loaded.
+
+```ts
+import {
+    MockRemoteViewControllerFactory,
+    RemoteViewControllerFactoryImpl,
+} from '@sprucelabs/spruce-heartwood-utils'
+```
+
+**Setup — inject the mock before your skill view creates its factory:**
+
+```ts
+protected async beforeEach() {
+    RemoteViewControllerFactoryImpl.Class = MockRemoteViewControllerFactory
+    MockRemoteViewControllerFactory.reset()
+
+    MockRemoteViewControllerFactory.dropInRemoteController(
+        'your-skill.some-card',
+        YourCardViewController
+    )
+}
+```
+
+**Get the mock instance to run assertions:**
+
+```ts
+const mockFactory = MockRemoteViewControllerFactory.getInstance()
+```
+
+**Available assertions:**
+
+```ts
+// Assert a specific card was loaded:
+mockFactory.assertFetchedRemoteController('your-skill.some-card')
+
+// Assert it was loaded with specific constructor options:
+mockFactory.assertFetchedRemoteController('your-skill.some-card', { organizationId: 'org-123' })
+
+// Assert a card was NOT loaded:
+mockFactory.assertDidNotFetchRemoteController('your-skill.other-card')
+
+// Assert a skill view renders a specific remote card:
+mockFactory.assertSkillViewRendersRemoteCard(this.vc, 'your-skill.some-card')
+
+// Assert constructor options match exactly:
+mockFactory.assertRemoteCardConstructorOptionsEqual('your-skill.some-card', { organizationId: 'org-123' })
+
+// Assert views were loaded for a namespace:
+mockFactory.assertLoadedViewsForNamespace('your-skill')
+```
+
+**Check without throwing:**
+
+```ts
+if (mockFactory.hasController('your-skill.some-card')) { ... }
+```
+
+---
+
+### `MockDroppedInControllers`
+
+Type for the map of card IDs to VC classes held by `MockRemoteViewControllerFactory`:
+
+```ts
+import { MockDroppedInControllers } from '@sprucelabs/spruce-heartwood-utils'
+
+type MockDroppedInControllers = Record<
+    string,
+    new (args: any) => ViewController<any>
+>
+```
+
+---
+
+## Device & Layout Utilities
+
+These utilities are not re-exported through the main barrel and must be imported directly from their build paths.
+
+### `getDeviceOrientation()`
+
+Returns `'landscape'` or `'portrait'` based on the current viewport dimensions. Use this to make layout decisions that depend on device orientation.
+
+```ts
+import { getDeviceOrientation } from '@sprucelabs/spruce-heartwood-utils/build/components/controlBars/getDeviceOrientation'
+
+const orientation = getDeviceOrientation()  // 'landscape' | 'portrait'
+
+if (orientation === 'landscape') {
+    // wide layout
+} else {
+    // tall layout
+}
+```
+
+**Decision logic:**
+
+```
+if (clientWidth > clientHeight && clientWidth > 700)  → 'landscape'
+else                                                   → 'portrait'
+```
+
+**Reacting to changes** — do not poll. Subscribe to the orientation change event instead:
+
+```ts
+await emitter.on('did-change-orientation', async () => {
+    const orientation = getDeviceOrientation()
+    // update layout
 })
 ```
 
-## Documentation
+**Caveats:** Browser-only. Synchronous. Each call reads the DOM live — no caching.
+
+---
+
+### `skillViewState`
+
+A singleton that reflects whether the currently active Heartwood skill view is in full-screen mode. Read this in your card components to skip height animations or adapt layout when the user is in full-screen.
+
+```ts
+import { skillViewState } from '@sprucelabs/spruce-heartwood-utils/build/components/skillViews/skillViewState'
+
+if (skillViewState.isFullScreen) {
+    // full-screen mode is active — skip height-dependent layout
+}
+```
+
+**In tests — reset between cases:**
+
+```ts
+beforeEach(() => {
+    skillViewState.isFullScreen = false
+})
+```
+
+**Caveats:** Plain object — not reactive. Reading it does not subscribe to changes. Must be reset between tests since it is a module-level singleton.
+
+---
+
+## Animation
+
+These are the same animation and layout primitives that Heartwood uses in its own card views. Import them to get consistent stagger, height animation, and absolute-positioning behavior in your skill's components.
+
+### Quick Start
+
+```ts
+import {
+    // Visibility queue
+    useQueueShow, useShowNow,
+    showRightAway, hideRightAway,
+    queueShow, queueHide,
+    queueCallback, callbackImmediately,
+    clearPendingHideAndQueueShow, clearPendingShowAndQueueHide,
+    stopQueue,
+    // Layout components
+    Sizer, DelayedPlacer,
+    // Utilities
+    sizeUtil, Settings,
+    // Types
+    AnimationEmitter,
+    SizerProps,
+    DelayedPlacerProps,
+} from '@sprucelabs/spruce-heartwood-utils'
+```
+
+---
+
+### Required CSS
+
+**Inside a Heartwood skill view:** all required CSS is already provided by Heartwood's stylesheet. No extra setup needed.
+
+**Outside Heartwood (standalone use):** supply the following rules yourself.
+
+The `queueShow` system toggles a `hidden` CSS class. Elements must start with `hidden` in their `className` and define their own transition:
+
+```css
+.hidden {
+    opacity: 0;
+    transform: translateY(4px);
+    pointer-events: none;
+}
+
+/* Transition goes on the element, not .hidden */
+.your-element {
+    transition: opacity 200ms ease, transform 200ms ease;
+}
+```
+
+`Sizer` uses `.sizer` and `.sizer__inner`:
+
+```css
+.sizer {
+    transition: height 500ms ease;
+    overflow: hidden;
+}
+```
+
+`DelayedPlacer` uses `.placer`. Its child must be `position: absolute`:
+
+```css
+.placer {
+    position: relative;
+}
+.placer > * {
+    position: absolute;
+}
+```
+
+---
+
+### System Architecture
+
+The animation system has three cooperating layers:
+
+```
+queueShow / queueHide          — staggered CSS class toggling (show/hide via .hidden)
+       │
+       ▼
+Sizer                          — measures content height, sets style.height for smooth animation
+       │  emits did-resize-content
+       ▼
+DelayedPlacer                  — reads Sizer's placeholder position, writes absolute coordinates
+```
+
+Pass the **same emitter instance** to `Sizer` and `DelayedPlacer` when they are siblings so their events coordinate. Different emitter instances decouple them.
+
+`Settings.disableAnimations()` is a global switch that makes every timeout fire at `0ms` and drains the queue synchronously — call it in your test `beforeEach` for deterministic tests.
+
+---
+
+### AnimationEmitter
+
+The interface `Sizer` and `DelayedPlacer` use to communicate layout-change events. You implement this and pass it as the `emitter` prop to coordinate components.
+
+```ts
+interface AnimationEmitter {
+    on(event: string, handler: () => void): Promise<void> | void
+    off(event: string, handler: () => void): Promise<void> | void
+    emit(event: string): Promise<void> | void
+}
+```
+
+**Events:**
+
+| Event | Who listens | Who emits | Meaning |
+|---|---|---|---|
+| `did-render` | Sizer, DelayedPlacer | your code | A React render cycle completed |
+| `did-resize` | Sizer, DelayedPlacer | your code | Viewport or parent dimensions changed |
+| `did-resize-content` | DelayedPlacer | Sizer | Sizer changed its measured height |
+| `did-change-orientation` | DelayedPlacer | your code | Portrait ↔ landscape switch |
+| `did-place-cards` | your listeners | DelayedPlacer | Placement calculation finished |
+
+**Minimal implementation:**
+
+```ts
+class SimpleEmitter implements AnimationEmitter {
+    private listeners: Record<string, Array<() => void>> = {}
+
+    on(event: string, handler: () => void): void {
+        ;(this.listeners[event] ??= []).push(handler)
+    }
+
+    off(event: string, handler: () => void): void {
+        this.listeners[event] = (this.listeners[event] ?? []).filter(
+            (h) => h !== handler
+        )
+    }
+
+    emit(event: string): void {
+        for (const h of this.listeners[event] ?? []) h()
+    }
+}
+```
+
+> Pass the **same function reference** to `on` and `off`. Inline arrow functions cannot be removed with `off`.
+
+---
+
+### Settings
+
+A static class that controls animation behavior globally. The most important method for skill developers is `disableAnimations()` — call it in every test `beforeEach`.
+
+```ts
+class Settings {
+    // Disable all animations. Makes timeouts fire at 0ms, queue drains synchronously.
+    // Cannot be undone. Never call in production code.
+    static disableAnimations(): void
+
+    static getIsAnimationEnabled(): boolean
+
+    // Returns animation duration in ms: landscape=500, portrait=1000. Returns 0 if disabled.
+    static get animationDuration(): number
+}
+```
+
+**In your test base class:**
+
+```ts
+protected async beforeEach() {
+    Settings.disableAnimations()
+}
+```
+
+> **One-way door:** there is no `enableAnimations()`. Each test file runs in its own module context so this is safe. Never call it in production.
+
+---
+
+### queueShow — Show/Hide Queue
+
+A singleton FIFO queue that staggers visibility transitions by toggling the CSS class `hidden` on DOM elements. Staggering class removals across a 40ms interval creates natural cascading fade-in effects.
+
+When animations are disabled (`Settings.disableAnimations()`), the entire queue drains synchronously — no real timers needed in tests.
+
+**The queue is shared** across your entire skill view. `stopQueue()` stops all pending operations.
+
+---
+
+#### `queueShow(refOrNode, delay?, method?)`
+
+Queues a show (removes `hidden`) on an element.
+
+```ts
+function queueShow(
+    refOrNode: React.RefObject<HTMLElement | null> | HTMLElement | null,
+    delay?: number,              // default: 40ms between queue steps
+    method?: 'push' | 'unshift' // default: 'push' (end of queue)
+): void
+```
+
+No-ops silently if the element is null, already visible, or already queued.
+
+```tsx
+// Standard pattern — queue on mount via ref callback:
+<div className="your-card hidden" ref={(ref) => { ref && queueShow(ref) }} />
+
+// Multiple elements — queue them all:
+const items = containerRef.current?.querySelectorAll('.item') ?? []
+for (const item of items) { queueShow(item as HTMLElement) }
+```
+
+---
+
+#### `queueHide(refOrNode, delay?, method?)`
+
+Queues a hide (adds `hidden`) on an element.
+
+```ts
+function queueHide(
+    refOrNode: React.RefObject<HTMLElement> | HTMLElement,
+    delay?: number,
+    method?: 'push' | 'unshift'
+): void
+```
+
+```ts
+queueHide(loadingSpinnerRef)
+```
+
+---
+
+#### `showRightAway(refOrNode)`
+
+Jumps to the **front** of the queue. Use when an element must appear before anything else already queued.
+
+```ts
+function showRightAway(
+    refOrNode: React.RefObject<HTMLElement | null> | HTMLElement
+): void
+```
+
+```tsx
+<div className="alert hidden" ref={(ref) => { ref && showRightAway(ref) }} />
+
+<img onLoad={() => { imageRef && showRightAway(imageRef) }} />
+```
+
+---
+
+#### `hideRightAway(refOrNode)`
+
+Jumps a hide to the front of the queue.
+
+```ts
+function hideRightAway(refOrNode: React.RefObject<HTMLElement> | HTMLElement): void
+```
+
+```ts
+hideRightAway(overlayRef.current)
+```
+
+---
 
-For comprehensive documentation, visit [developer.spruce.bot](https://developer.spruce.bot).
+#### `queueCallback(cb)`
+
+Inserts an arbitrary callback at the end of the queue. Runs in sequence with show/hide steps.
+
+```ts
+function queueCallback(cb: () => void): void
+```
+
+```ts
+// Trigger a re-render after queued animations complete:
+queueCallback(() => this.triggerRender())
+```
+
+---
+
+#### `callbackImmediately(cb)`
+
+Inserts a callback at the front of the queue.
+
+```ts
+function callbackImmediately(cb: () => void): void
+```
+
+```ts
+const enqueue = shouldPrioritize ? callbackImmediately : queueCallback
+enqueue(() => this.handleReady())
+```
+
+---
+
+#### `clearPendingHideAndQueueShow(refOrNode, delay?)`
+
+Cancels a pending hide and queues a show for elements toggled back before their hide ran.
+
+> Prefer `showRightAway()` for most toggle cases.
+
+---
+
+#### `clearPendingShowAndQueueHide(refOrNode, delay?)`
+
+Cancels a pending show and queues a hide.
+
+> Prefer `hideRightAway()` for most toggle cases.
+
+---
+
+#### `stopQueue()`
+
+Stops the queue interval and abandons any remaining items. Call in test teardown to prevent queue state leaking between tests.
+
+```ts
+protected async afterEach() {
+    await super.afterEach()
+    stopQueue()
+}
+```
+
+---
+
+#### `useQueueShow(ref, delay?)` — React Hook
+
+Calls `queueShow` on every render via `useEffect`. Use for elements that should fade in after each render.
+
+```tsx
+const ref = useRef<HTMLDivElement>(null)
+useQueueShow(ref)
+
+return <div ref={ref} className="your-panel hidden">...</div>
+```
+
+---
+
+#### `useShowNow(ref, delay?)` — React Hook
+
+Like `useQueueShow` but places itself at the front of the queue on every render.
+
+```ts
+function useShowNow(ref: React.RefObject<HTMLElement>, delay?: number): void
+```
+
+---
+
+### Sizer — Animated Height Container
+
+Wraps children in a div whose `height` is set via inline style to match the measured height of its content. Listens to `did-render` and `did-resize` events so it resizes whenever layout changes — enabling smooth CSS height transitions on content that would otherwise be `height: auto`. Emits `did-resize-content` so `DelayedPlacer` can re-place after a height change.
+
+#### Props (`SizerProps`)
+
+```ts
+interface SizerProps {
+    children: any
+
+    // When false, renders children with no wrapper. Default: enabled.
+    isEnabled?: boolean
+
+    // CSS class on the outer .sizer div.
+    className?: string
+
+    // When true, starts at height 0 and defers first measurement by 100ms.
+    // Use for content that should animate in from nothing.
+    shouldStartAtZero?: boolean
+
+    // When true, keeps overflow hidden throughout. When explicitly false,
+    // overflow is always visible (adds force-show-overflow class).
+    shouldHideOverflow?: boolean
+
+    // Event emitter. Without one, Sizer only resizes on React re-renders,
+    // not in response to external layout events.
+    emitter?: AnimationEmitter
+}
+```
+
+#### Ref API
+
+```ts
+sizer.current?.resize(): boolean    // measure and apply new height; returns true if it changed
+```
+
+#### Emitter Events
+
+| Event | Direction | Meaning |
+|---|---|---|
+| `did-render` | listened | Re-rendered; measure and resize |
+| `did-resize` | listened | Viewport changed; measure and resize |
+| `did-resize-content` | emitted | Height changed (fires after `Settings.animationDuration` ms) |
+
+#### Usage
+
+```tsx
+// Simplest — just clip overflow during height transition:
+<Sizer shouldHideOverflow>
+    {isExpanded && <YourExpandableContent />}
+</Sizer>
+
+// Animate in from zero height:
+<Sizer emitter={emitter} shouldStartAtZero>
+    <YourCard />
+</Sizer>
+
+// Manually trigger resize when content changes outside React state:
+const emitter = useMemo(() => new SimpleEmitter(), [])
+const sizer = useRef<React.ElementRef<typeof Sizer>>(null)
+
+<Sizer shouldHideOverflow ref={sizer} emitter={emitter}>
+    <YourDynamicContent
+        onContentChange={async () => {
+            if (sizer.current?.resize()) {
+                await emitter.emit('did-resize')
+            }
+        }}
+    />
+</Sizer>
+
+// Staggered entrance with queueShow:
+<Sizer emitter={emitter} shouldHideOverflow shouldStartAtZero>
+    <div className="your-item hidden" ref={(ref) => { ref && queueShow(ref) }}>
+        content
+    </div>
+</Sizer>
+```
+
+> Do not nest `Sizer` inside another `Sizer` for the same content — they will conflict.
+
+---
+
+### DelayedPlacer — Absolute Positioning
+
+Positions a child element to match the location of its in-flow placeholder. Wraps children in a `position: relative` placeholder div, measures the placeholder's `offsetLeft`/`offsetTop`, and writes those values as `style.left` / `style.top` on the child. The deferred measurement lets the layout settle before placement, enabling cards and overlays to animate smoothly into position.
+
+When `isEnabled={false}`, children render inline with no wrapper.
+
+#### Props (`DelayedPlacerProps`)
+
+```ts
+interface DelayedPlacerProps {
+    children: any
+
+    // Required. When true, wraps in .placer and manages absolute positioning.
+    isEnabled: boolean
+
+    // Required. CSS class on the outer .placer div.
+    className: string
+
+    // Event emitter. Listens for layout changes to re-measure and re-place.
+    emitter?: AnimationEmitter
+
+    // Required. Return true when this skill view is focused and in the foreground.
+    // Placement is skipped when false to avoid measuring off-screen content.
+    // Pass () => true for standalone use outside Heartwood.
+    isFocused: () => boolean
+}
+```
+
+#### Ref API
+
+```ts
+delayedPlacer.current?.placeRightAway(): void  // re-measure and re-place immediately
+```
+
+#### Emitter Events
+
+| Event | Direction | Meaning |
+|---|---|---|
+| `did-resize-content` | listened | Sizer changed height; re-place |
+| `did-resize` | listened | Viewport changed; re-place |
+| `did-render` | listened | Re-rendered; re-place |
+| `did-change-orientation` | listened | Device rotated; re-place |
+| `did-place-cards` | emitted | Placement finished (100ms after measuring) |
+
+#### Usage
+
+```tsx
+const placerRef = React.createRef<DelayedPlacer>()
+
+// Re-place after content changes:
+private onContentChange() {
+    setTimeout(() => { placerRef.current?.placeRightAway() }, 50)
+}
+
+render() {
+    return (
+        <DelayedPlacer
+            className="placer__card"
+            isEnabled={this.isPlacementEnabled}
+            emitter={this.emitter}
+            ref={placerRef}
+            isFocused={() => true}
+        >
+            {yourCard}
+        </DelayedPlacer>
+    )
+}
+```
+
+> `isEnabled`, `className`, and `isFocused` are all required. The child must be `position: absolute` in CSS for placement to have visual effect.
+
+---
+
+### sizeUtil — DOM Measurement
+
+A collection of DOM measurement helpers. Use these in your components when you need to measure element dimensions or positions the same way Heartwood does.
+
+```ts
+const sizeUtil = {
+    bodyWidth(): number
+    bodyHeight(): number
+
+    // Absolute position (walks offsetParent chain, accounts for scroll)
+    getTop(node: HTMLElement): number
+    getLeft(node: HTMLElement): number
+    getBottom(node: HTMLElement): number
+    getRight(node: HTMLElement): number
+    getPosition(node: HTMLElement): { x: number; y: number }
+
+    // Local position relative to offsetParent
+    getLocalTop(node: HTMLElement): number
+    getLocalLeft(node: HTMLElement): number
+    getLocalBottom(node: HTMLElement): number
+    getLocalRight(node: HTMLElement): number
+
+    // Dimensions
+    getWidth(node: HTMLElement): number
+    getHeight(node: HTMLElement, shouldGetPreciseHeight?: boolean): number
+    //  true (default): getBoundingClientRect().height — sub-pixel, correct during transitions
+    //  false: offsetHeight — integer, cheaper
+
+    // Scroll
+    getScrollWidth(node: HTMLElement): number
+    getScrollHeight(node: HTMLElement): number
+    getMaxScrollTop(node: HTMLElement): number
+    getMaxScrollLeft(node: HTMLElement): number
+    isScrolledAllTheWayRight(node: HTMLElement): boolean
+    isScrolledAllTheWayLeft(node: HTMLElement): boolean
+
+    // Hit testing
+    doesIntersect({ x, y, node }: { x: number; y: number; node: HTMLElement }): boolean
+}
+```
+
+`getPosition()` returns **absolute page coordinates** (distance from top-left of document), not viewport coordinates.
+
+**Stubbing in tests** — `sizeUtil` is a plain object so individual methods are replaceable:
+
+```ts
+sizeUtil.bodyWidth = () => 1200
+```
+
+> Call measurement methods after layout has settled — inside `componentDidMount`, after `setTimeout`, or in an emitter event handler.
+
+---
+
+### How the Three Systems Coordinate
+
+A complete example showing all three systems working together in a card component:
+
+```tsx
+import {
+    Sizer, DelayedPlacer, queueShow, Settings, AnimationEmitter,
+} from '@sprucelabs/spruce-heartwood-utils'
+
+class SimpleEmitter implements AnimationEmitter {
+    private listeners: Record<string, Array<() => void>> = {}
+    on(event: string, handler: () => void) { (this.listeners[event] ??= []).push(handler) }
+    off(event: string, handler: () => void) {
+        this.listeners[event] = (this.listeners[event] ?? []).filter(h => h !== handler)
+    }
+    emit(event: string) { for (const h of this.listeners[event] ?? []) h() }
+}
+
+function YourCard({ isPlaced, isFocused }: { isPlaced: boolean; isFocused: () => boolean }) {
+    const emitter = useMemo(() => new SimpleEmitter(), [])
+
+    return (
+        <DelayedPlacer
+            className="placer__card"
+            isEnabled={isPlaced}
+            emitter={emitter}
+            isFocused={isFocused}
+        >
+            <Sizer emitter={emitter} shouldHideOverflow shouldStartAtZero>
+                <div
+                    className="card hidden"
+                    ref={(ref) => { ref && queueShow(ref) }}
+                >
+                    your content
+                </div>
+            </Sizer>
+        </DelayedPlacer>
+    )
+}
+```
+
+**What happens when content renders:**
+
+```
+React render
+    → Sizer receives did-render → measures height → updates style.height
+    → Sizer emits did-resize-content (after animation duration)
+        → DelayedPlacer re-measures placeholder → updates style.left / style.top
+        → DelayedPlacer emits did-place-cards
+queueShow removes .hidden from each element with a 40ms stagger
+```
+
+**Test setup for animation components:**
+
+```ts
+protected async beforeEach() {
+    Settings.disableAnimations()
+    skillViewState.isFullScreen = false
+}
+
+protected async afterEach() {
+    await super.afterEach()
+    stopQueue()
+}
+```

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sprucelabs/spruce-heartwood-utils",
 	"description": "Heartwood Utilities",
-	"version": "38.16.1",
+	"version": "38.16.2",
 	"skill": {
 		"namespace": "heartwood"
 	},