noob-components/.trellis/spec/plugs-composables/use-watch-once.md

# useWatchOnce (watchEffectOnce)

> One-time watch utility that auto-unmounts after condition is met.

## Purpose

Executes a callback once when a reactive condition becomes truthy, then automatically stops watching.

## Signature

```typescript
export function watchEffectOnce(cond: Ref<any, any>, cb: WatchEffect): WatchStopHandle
```

## Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `cond` | `Ref<any>` | Reactive condition to watch |
| `cb` | `WatchEffect` | Callback when condition is true |

## Return Value

| Type | Description |
|------|-------------|
| `WatchStopHandle` | Function to manually stop the watcher |

## Usage Pattern

```typescript
// Example: plugs/composables/useWatchOnce.ts
import { ref } from "vue";
import { watchEffectOnce } from "plugs/composables";

const isReady = ref(false);

watchEffectOnce(isReady, (onCleanup) => {
  console.log("Ready!");
  // Optional: register cleanup
  onCleanup(() => {
    console.log("Cleanup when stopped");
  });
});

isReady.value = true; // Triggers callback and stops watching
```

## Key Implementation Details

1. **Auto-stop**: Uses `nextTick` + `stop()` after condition is met
2. **One-shot**: Callback fires only on first truthy value
3. **Cleanup support**: Passes `onCleanup` callback for disposal logic

## Dependencies

- `vue` - `nextTick`, `ref`, `watchEffect`

## Anti-patterns

- Do not use for ongoing watches; this is specifically for one-time triggers
- Do not rely on the watcher persisting; it stops after first trigger