npm package: @sable-ai/core
Description: Shared types and utilities for Sable AI SDK packages
Latest version: 0.1.6

## Utilities in `src/utils/`

- **`Browser.ts`** — Safe browser checks and globals.
  - Exports: `isBrowser`, `safeWindow`, `safeDocument`.

- **`Http.ts`** — Lightweight HTTP client wrapper.
  - Exports: `HttpClient`.

- **`ElementSelector.ts`** — Find single or multiple elements, wait for elements.
  - Exports: `findElement`, `findElements`, `waitForElement`.

- **`ElementPositioning.ts`** — Helpers for positioning and observation.
  - Exports: `getElementPosition`, `isElementInViewport`, `applyPositionWithDelay`,
    `createPositionObserver`, `removePositionObserver`, `cleanupAllPositionObservers`.

- **`HighlightElement.ts`** — Visual pulsing highlight with auto-restore.
  - Exports: `highlightElement`.

- **`ScrollToElement.ts`** — Scroll an element into view with optional highlight.
  - Exports: `scrollToElement`.

- **`AudioAnalyzer.ts`** — Audio volume analysis utilities.
  - Exports: `AudioVolumeAnalyzer`.

# @sable-ai/core

Core utilities for DOM interaction and client automation.

This package is ESM-first and exposes utilities like `highlightElement` and `scrollToElement` for visual guidance and in-page navigation.

## Installation

This package is part of the monorepo and is consumed by sibling packages. If you want to use it externally, install via your package manager after publishing.

## Build

From `packages/core/`:

```bash
npm run build
```

This generates:
- `dist/esm/` — ES modules (used by the visual test page)
- `dist/cjs/` — CommonJS builds
- `dist/types/` — TypeScript declarations

## Visual testing (no React app required)

A minimal HTML page is provided to visually test the helpers.

1) Build the package (if you haven't already):
```bash
npm run build
```

2) Serve `packages/core/` as the web root (so that `/test/` and `/dist/esm/` are accessible):
```bash
npx serve
```

3) Open the test page in your browser:
- http://localhost:3000/test/

If you serve from the monorepo root instead, use:
- http://localhost:3000/packages/core/test/

The page at `packages/core/test/index.html` loads the built ESM files directly:
- `../dist/esm/utils/highlightElement.js`
- `../dist/esm/utils/scrollToElement.js`

Buttons on the page let you:
- **Highlight**: run `highlightElement()` with default yellow pulsing outline and auto-restore.
- **Flash (1s)**: run `highlightElement()` with an orange style for 1 second.
- **Scroll + Highlight**: run `scrollToElement()` which scrolls and calls `highlightElement()`.

## API

- **highlightElement(element, options?, timeMs?) => Promise<void>**
  - Temporarily applies a prominent yellow pulsing outline to `element`, then restores original inline styles.
  - Options (all optional):
    - `color` (default: `rgb(204, 184, 0)`)
    - `width` (default: `2.5px`)
    - `duration` — CSS transition duration, e.g. `"0.5s"` (default `0.5s`)
  - `timeMs` — how long to keep the highlight before restoring (default `1000`).

- **scrollToElement(element, options?) => Promise<void>**
  - Scrolls `element` into view and optionally highlights it.
  - Options (all optional):
    - `behavior` (default: `"smooth"`)
    - `block` (default: `"center"`)
    - `inline` (default: `"nearest"`)
    - `highlight` (default: `true`)
    - `highlightOptions` — forwarded to `highlightElement()`
    - `highlightDurationMs` — duration passed to `highlightElement()` (default `1000`)

## Notes

- This package is ESM-first. When importing in the browser, relative imports include the `.js` extension (e.g., `./Browser.js`). The visual test page imports from `dist/esm/` for this reason.
- If your browser blocks `file://` ESM imports, use `npx serve` (or any static server) as shown above.
- Downstream packages should import from the top-level entry: `@sable-ai/core`.

## Development

- Type-check/build: `npm run build`
- Linting/tests are configured in the monorepo; run them at the root if applicable.