Wanderpage

Wanderpage is a free, local-first vacation story generator: point it at a photo folder and it builds a private, static, cinematic travel story. Originals are never modified. Published images are resized WebP files with metadata removed; public route coordinates are rounded; low-confidence locations are omitted or broadened; people are never identified.

Quickstart

Requirements: Node.js 24.18.0, pnpm (npm install -g pnpm), and macOS sips for HEIC fallback when Sharp/libvips cannot decode a file. If pnpm is missing, npx @buildproven/wanderpage tells you so and exits — install it and re-run the same command.

npx @buildproven/wanderpage

This creates a ./wanderpage project folder, installs dependencies, and opens Studio in your browser — nothing runs anywhere but your machine. Pass a folder name to scaffold somewhere else (npx @buildproven/wanderpage my-trips), or re-run the same command later to relaunch Studio in an existing project.

Set OPENAI_API_KEY for real vision analysis and narrative generation — add it to the generated project's .env.local. The model names and Wikimedia user agent are configurable in .env.example. Vercel may use an existing CLI login or VERCEL_TOKEN.

Cloning instead

If you'd rather work from a git clone (for contributing, or to track the source directly):

git clone https://github.com/buildproven/wanderpage.git
cd wanderpage
pnpm install
cp .env.example .env.local

Open the local app

On macOS, double-click Open Wanderpage.command. Or launch the same local interface from a terminal:

pnpm studio

Wanderpage builds the interface, opens it in the default browser, and listens only on 127.0.0.1. Choose a photo folder, set the people and route privacy controls, and select Build my Wanderpage. The app shows live progress, the selected edit, rejected-photo counts, the local decision report, and the finished trip. Only one trip runs at a time.

The permanent sample stays at /demo. Generated trips receive readable title-based pages such as /trips/oregon-coast; separate titles are preserved as separate pages under data/trips/.

Generate a story

pnpm trip --input "/absolute/path/to/vacation-photos" --people include --title "Oregon Coast 2026"
pnpm trip:list
pnpm trip:publish oregon-coast-2026
pnpm build
pnpm preview

New trips are private drafts: their images stay outside the static site until you publish them. In Studio, review the draft and use Publish this story. From the CLI, use pnpm trip:list to find the generated slug, then pnpm trip:publish <slug> before building. pnpm trip:unpublish <slug> removes a trip and its assets from the next static export.

Strict people exclusion requires the vision API so the tool can conservatively filter visible people:

pnpm trip --input "/absolute/path/to/vacation-photos" --people exclude --max-photos 36 --privacy approximate

Supported inputs are nested JPEG/JPG, PNG, WebP, HEIC, and HEIF folders. --max-photos accepts 12–60. Add --dry-run for local reports only, --force to invalidate caches, and --deploy to build and create a Vercel preview deployment.

Deterministic demo

No API key or private photos are needed:

pnpm trip:demo
pnpm build
pnpm preview

The exact static output is out/. Local-only reports are written under .trip-output/; cache artifacts live under .trip-cache/. Neither directory is exported.

Quality gates

pnpm typecheck
pnpm lint
pnpm test
pnpm trip:demo
pnpm build
pnpm privacy
pnpm exec playwright install chromium
pnpm test:e2e

pnpm test includes a fixture-driven integration test that creates a temporary nested photo folder with JPEG, WebP, duplicate, EXIF/GPS, and (on macOS) HEIC inputs. It runs the production pipeline, builds an isolated static Next.js export, applies the privacy and 90 MB budget checks, then opens the generated story in Chromium. Temporary originals and outputs are removed after the run.

The external OpenAI path is an explicit paid/network smoke test rather than part of every local test run:

OPENAI_API_KEY=... pnpm test:live

It sends a small contact sheet through the configured vision model using Structured Outputs, generates the narrative, and validates the resulting manifest. Wikipedia/Wikimedia and weather remain graceful network enrichments; deterministic test substitutes cover their pipeline contracts during the default integration test.

Environment

• OPENAI_API_KEY: required for real AI-backed generation and strict people exclusion.
• OPENAI_VISION_MODEL: defaults to gpt-5.6-luna.
• OPENAI_WRITER_MODEL: defaults to gpt-5.6-terra.
• WIKIMEDIA_USER_AGENT: descriptive API user agent.
• WANDERPAGE_PORT: optional local Studio port; defaults to 4317 on 127.0.0.1.
• VERCEL_TOKEN: optional when the Vercel CLI is already authenticated.
• WANDERPAGE_WORKSPACE: optional advanced override for writing generated data, cache, reports, and public assets into an isolated workspace; the integration suite uses this to protect the repository checkout.

Online enrichment uses Wikipedia/Wikimedia and Open-Meteo during generation only. Their failure degrades to a complete photo-led story without unsupported facts; the exported site makes no runtime API calls.