# How ego-lite's help() Function Is Powered by Runtime JSDoc Parsing: A Technical Deep Dive

> Discover how ego-lite's help() function uses runtime JSDoc parsing to serve API docs on demand without file-system access. Learn the technical details.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: deep-dive
- Published: 2026-08-01

---

**ego-lite's `help()` function generates runtime API documentation by embedding JSDoc-extracted metadata as JSON during the build process, then parsing and serving it on demand without file-system access.**

The `ego-lite` browser automation library equips AI agents with a self-documenting runtime. Its `help()` helper lets agents discover available helpers and their signatures without ever reading source files. This article explains how build-time JSDoc parsing, JSON embedding, and runtime caching work together to power this feature.

## Build-Time JSDoc Extraction with Acorn

The documentation pipeline begins in `scripts/build.mjs`. During the bundle step, the build script parses the source code using **Acorn** to extract JSDoc comments attached to every exported helper.

The collected documentation is serialized to JSON and **injected** into [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) by replacing the placeholder `__EGO_EMBEDDED_HELP_DOCS__`. This transformation happens before the final bundle is produced, ensuring the documentation ships with the runtime.

```javascript
// Simplified representation of the build injection
// In scripts/build.mjs:
const docs = extractJSDocFromExports(ast); // Acorn-based extraction
const json = JSON.stringify(docs);

// Injected into src/help-runtime.ts before build completion
const EMBEDDED_DOCS_JSON = /* __EGO_EMBEDDED_HELP_DOCS__ */ json;

```

## Embedding Documentation in the Runtime

The constant `EMBEDDED_DOCS_JSON` at line 26 of [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) holds the injected JSON string. This design choice is critical: the runtime never attempts file-system operations, which would fail inside the browser sandbox where `ego-lite` executes from a non-readable `ego://` URL.

At runtime, the `parseEmbeddedDocs()` function (lines 88-96) handles JSON parsing:

```typescript
// From src/help-runtime.ts
function parseEmbeddedDocs(): Map<string, HelperDoc> {
  const parsed = JSON.parse(EMBEDDED_DOCS_JSON);
  return new Map(Object.entries(parsed));
}

```

The resulting `Map<string, HelperDoc>` is cached (lines 28-30, 79-86) to avoid re-parsing on subsequent `help()` calls.

## The Public help() Helper Interface

The `helperContext()` function in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 22-49) constructs the façade exposed to agents. It injects a `help` method that delegates to `helpRuntime()`:

```typescript
// From src/helpers.ts lines 40-44
help: async (...names: string[]) => {
  return helpRuntime(allHelpers, ...names);
}

```

The `helpRuntime()` implementation (lines 30-55 in [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts)):
- Looks up requested helper names in the cached docs map
- Returns a single `HelperDoc`, an array of docs, or a façade overview
- Returns an error string for unknown helpers

```javascript
// Runtime usage examples
const all = await help();           // All exported helpers
const clickDoc = await help('click'); // Specific helper documentation
const pageOverview = await help('page'); // Façade summary string

```

## Formatting Output for Readability

When `helpRuntime()` retrieves a `HelperDoc` object, `formatHelp()` (lines 57-77) transforms it into a markdown-style string. The formatter extracts:

- **Description** from the JSDoc comment body
- **@param** entries with name, type, and description
- **@returns** type and description
- **Function signature** reconstructed from parsed metadata

```javascript
// Example output from formatHelp()
/*
Click the element matching the selector

@param selector: string — CSS selector of the element
@param options?: object — Click options (button, clickCount, delay)
@returns: Promise<void>

click(selector, options?)
*/

```

## Why This Architecture Matters

The "runtime JSDoc parsing" description requires clarification: JSDoc parsing happens **at build time**, but the results are **parsed from JSON at runtime**. This two-phase approach delivers three key benefits:

1. **Sandbox compatibility** — No file-system access required inside the browser environment
2. **Performance** — Single JSON parse cached for all subsequent lookups
3. **Freshness** — Documentation always matches the shipped code version

## Summary

- **Build phase**: `scripts/build.mjs` uses Acorn to extract JSDoc, injects JSON into [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts)
- **Runtime embedding**: `EMBEDDED_DOCS_JSON` holds serialized documentation; `parseEmbeddedDocs()` creates a cached Map
- **Public API**: `help()` in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) delegates to `helpRuntime()` for lookup and `formatHelp()` for presentation
- **Output formats**: Single helper docs, arrays of docs, façade summaries, or error strings

## Frequently Asked Questions

### What is the difference between JSDoc parsing and runtime documentation retrieval?

JSDoc parsing occurs during the build process when `scripts/build.mjs` analyzes the source code with Acorn. Runtime documentation retrieval means the `help()` function accesses pre-parsed, JSON-serialized documentation that was embedded in the bundle — no source files are read at execution time.

### Why doesn't ego-lite parse JSDoc comments directly at runtime?

Direct JSDoc parsing would require file-system access to read source files, which is impossible within `ego-lite`'s browser sandbox environment. The runtime executes from an `ego://` URL where source files are not accessible. Pre-embedding the parsed documentation as JSON eliminates this dependency.

### How does the help() function handle unknown helper names?

When `helpRuntime()` receives a name not found in the docs Map, it returns an error string indicating the helper does not exist. This validation happens at line 30-55 of [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) before any formatting occurs.

### Can developers customize the documentation output format?

The `formatHelp()` function in [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) (lines 57-77) controls all markdown-style formatting. Developers could modify this function to change output structure, though the JSON schema embedded at build time would remain unchanged.