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

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 by replacing the placeholder __EGO_EMBEDDED_HELP_DOCS__. This transformation happens before the final bundle is produced, ensuring the documentation ships with the runtime.

// 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 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:

// 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 (lines 22-49) constructs the façade exposed to agents. It injects a help method that delegates to helpRuntime():

// 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):

• 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

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

// 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
• Runtime embedding: EMBEDDED_DOCS_JSON holds serialized documentation; parseEmbeddedDocs() creates a cached Map
• Public API: help() in 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 before any formatting occurs.

Can developers customize the documentation output format?

The formatHelp() function in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}