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
- 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
- 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.