ChaiSpots

ChaiSpots is a local Node/browser tool for building Veeva-style interactive Key Message presentations from imported slides, PDFs, images, videos, overlays, hitspots, and custom code.

The tool runs locally, launches a browser-based builder, and exports delivery-ready Key Message folders/ZIPs.

Status

ChaiSpots is currently pre-release and under active development.

The main CLI command is:

chaispots

The preferred alias is:

chai-spots

Older Veeva-specific command names should be considered legacy.

Requirements

Node.js and npm

ChaiSpots is a Node ESM package and requires a modern Node/npm environment.

Recommended development environment:

Node.js 20+
npm 10+

The project has been developed/tested with Node 24.

Ghostscript

Ghostscript is required for PDF import/conversion.

Install Ghostscript before using PDF import.

macOS / Homebrew:

brew install ghostscript

Ubuntu / Debian:

sudo apt install ghostscript

Windows:

Install Ghostscript using the official Windows installer, then make sure the gs executable is available from your terminal path.

Confirm installation:

gs --version

If Ghostscript is missing, the builder can still run, but PDF import will fail.

Install package dependencies

From the ChaiSpots package root:

nvm use v24
npm install

Link the CLI during local development

From the package root:

npm link

Then confirm the CLI is available:

chaispots --help
chai-spots --help

Recommended development workflow

Use one folder for the package source and a separate folder for test projects.

Dev/
  chai-spots-veeva-npm/
  chaispots-test-project/

From the package root:

cd /path/to/chai-spots-veeva-npm
npm install
npm link

From an empty test/client project folder:

cd /path/to/chaispots-test-project
chaispots watch

This keeps package-owned source separate from project-owned files.

Package root vs project root

ChaiSpots uses two important locations.

Package root

The package root contains the reusable tool source:

app/
src/
bin/
package.json
README.md

It owns:

builder source
server routes
build tasks
docs
runtime files
export logic
templates

Project root

The project root is the folder where chaispots is launched.

It owns:

project state
imported slides
imported assets
imported videos
preview output
export output
recovery data

The package should not write project data into the package source folder unless you intentionally run the builder from the package root for testing.

Common commands

Start the builder server:

chaispots start

Build, watch source files, start the server, and open the builder:

chaispots watch

Build the browser app only:

chaispots build

Open the user guide:

chaispots docs

Open the developer guide:

chaispots devdocs

Show terminal help:

chaispots --help

npm scripts

From the package root, common development scripts are:

npm run build
npm run watch
npm run docs
npm run devdocs

If a script is unavailable, use the matching CLI command directly.

Local guides

ChaiSpots includes local package-owned documentation.

User guide:

chaispots docs

Developer guide:

chaispots devdocs

The user guide explains how to operate the tool.

The developer guide explains how the tool is structured internally.

Project output

ChaiSpots creates project-owned folders in the folder where the command is launched.

Current/target project structure:

project-folder/
  chaispots.json
  assets/
  slides/
  thumbs/
  videos/
  preview/
  export/
  recovery/

Folder purpose:

assets/    Supporting files imported into Key Messages or Shared Resources
slides/    Imported slide artwork from PDFs or image sequences
thumbs/    Builder thumbnails
videos/    Imported video files
preview/   Local browser preview output
export/    Local/Veeva export output
recovery/  Recovery snapshots

Older development builds may still create _chaispots_projects/current/. The intended pre-release direction is a flatter project-root structure.

Builder output

The package may create a package-owned builder output folder:

_chaispots_builder/

This folder is safe to rebuild and should contain only reusable builder UI output.

It should never contain client/project-specific data such as imported slides, videos, hitspots, project settings, previews, or exports.

Basic usage flow

1. Install dependencies.
2. Install Ghostscript.
3. Link or install the package.
4. Create/open a project folder.
5. Run chaispots watch.
6. Import slides, PDFs, or images.
7. Add hitspots, overlays, videos, assets, and custom code.
8. Save the project.
9. Build a preview.
10. Export the final delivery output.

Importing

ChaiSpots supports or is intended to support:

PDF import/conversion
image sequence import
static asset import
video import
overlay image import

PDF import requires Ghostscript.

Imported slide artwork should be optimized using the shared slide image settings, including max width and image quality.

Preview

Preview builds a local browser version of the project for testing interactions before export.

Use preview to test:

Key Message navigation
hitspots
overlays
videos
custom code
Shared Resources
direct-only slides
swipe behavior

Export

Export builds local delivery output, including Key Message folders/ZIPs, Shared Resources, runtime files, and diagnostics.

Typical export output lives under:

export/

Generated export files should usually be rebuilt from the builder rather than edited manually.

Runtime API

Exported Key Messages expose a runtime API on:

window.CHAI
window.SPOTS

Common helpers include:

CHAI.gotoKeyMessage(id)
CHAI.gotoPrevious()
CHAI.overlay.show(id)
CHAI.overlay.hide(id)
CHAI.overlay.toggle(id)
CHAI.overlay.hideAll()
CHAI.storage.get(key, fallback)
CHAI.storage.set(key, value)
CHAI.storage.remove(key)
CHAI.getPreviousKeyMessageId()
CHAI.getLastPageViewElapsedMinutes()

Use the local guide for the full CHAI API reference.

Troubleshooting

Port already in use

macOS/Linux:

lsof -i :3000
lsof -ti :3000 | xargs kill -9

Windows PowerShell:

netstat -ano | findstr :3000
taskkill /PID <PID> /F

PDF import fails

Check Ghostscript:

gs --version

If the command fails, install Ghostscript or fix your terminal path.

CLI command not found

Relink the package:

cd /path/to/chai-spots-veeva-npm
npm link

Then retry:

chaispots --help

Wrong project folder

Confirm you launched chaispots from the folder that should own the project files.

pwd
chaispots watch

Development notes

Keep these boundaries clear:

HTML owns structure.
CSS owns presentation.
JS owns behavior/state.
Node tasks own filesystem/build/import/export workflows.
Runtime files own exported presentation behavior.

Avoid:

project data in package folders
hardcoded project paths
duplicated import/export image processing
builder-only logic inside runtime output
runtime behavior hidden inside UI modules

License

Private/internal package.

https://lucide.dev/icons/