OrcaCast is a Salish Sea trip-planning and exploration application. It combines historical orca activity, forecast surfaces, weather, and local access information to help people choose dates and places for responsible, shore-first wildlife viewing.
The application is a React and TypeScript single-page app built with Vite. Its maps use MapLibre, H3 forecast grids, and locally packaged public data.
OrcaCast provides relative activity guidance, not real-time whale tracking or a guarantee of a sighting. Always follow current wildlife, marine, park, and safety guidance.
The Home page introduces OrcaCast and gives visitors a quick seasonal pulse before they start planning. It highlights the current week's historical activity, shows a compact Friday Harbor weather outlook, summarizes typical sightings through the year, and routes visitors into the Planner or Watch experiences.
Key capabilities:
- Current-week historical activity summary
- Seasonal activity chart and short-range weather context
- Direct entry points to trip planning, forecast exploration, cameras, and hydrophones
- Responsible-use framing for the rest of the application
The Watch page is the interactive forecast workspace. It overlays relative activity on the Salish Sea, provides a week-by-week timeline, and pairs the forecast with practical places where visitors can observe from shore, ferries, parks, or marinas.
Key capabilities:
- Interactive forecast map with activity legend, selectable color palettes, and hotspot controls
- Weekly forecast navigation and playback
- Ranked Field Picks with place details and map focus
- Park, marina, ferry, camera, and Orcasound hydrophone layers
- Itinerary building, reordering, map preview, and export
- Map reset, snapshot download, and sharing tools
The Planner turns a visitor's dates, base location, and optional travel range into a more focused Salish Sea trip view. After a plan is submitted, it presents seasonal context, a mapped travel area, recommended viewing locations, and tools for assembling an itinerary.
Key capabilities:
- Base-location, arrival-date, departure-date, and travel-distance inputs
- Seasonal activity comparison for the selected travel window
- Forecast map constrained around the trip plan
- Recommended viewing spots with filters and detail views
- Camera and hydrophone discovery
- Persisted plan state and itinerary export
The About page explains how to interpret OrcaCast. It describes the signals used by the application, what the forecast can and cannot do, the geographic scope, data freshness, and responsible viewing principles.
Key capabilities:
- Plain-language overview of sightings, weather, seasonal patterns, and local access data
- Forecast workflow and interpretation guidance
- Clear limitations and uncertainty framing
- Responsible viewing guidance and links to official resources
- Current data and regional coverage context
The Model Methodology page provides a deeper, visual walkthrough of the layers behind the forecast. It follows the model from seasonal history and recent activity through observer effort, spatial context, environmental proxies, uncertainty, and personalized viewing opportunity.
Key capabilities:
- Ten-stage explanation of the forecast and planning pipeline
- Status labels distinguishing current, integrating, and personalization layers
- Details on observer bias, spatial context, ecological proxies, and uncertainty
- Interpretation guidance for relative activity and viewing opportunity
Explore is a dedicated, coming-soon field-guide experience. It previews practical content about Salish Sea whales, responsible whale watching, species identification, and other wildlife visitors may encounter, including porpoises, seals, sea lions, eagles, and seabirds.
The route is available now so navigation, bookmarks, and sharing remain stable while the full guide is developed. Its construction treatment deliberately distinguishes preview content from finished guidance.
Planned topics:
- Orca, humpback, gray, and minke whale identification
- Shore-first and responsible whale-watching practices
- Seasonal and behavioral clues to look for
- Porpoises, pinnipeds, seabirds, and other Salish Sea wildlife
Unknown URLs render a responsive OrcaCast 404 page rather than an empty application shell. Its destination links are generated from the route registry. Static hosting must still serve index.html as the fallback so React Router can resolve direct requests.
- Node.js 18 or newer (Node.js 20 recommended)
- npm
npm install
npm run devVite prints the local development URL when the server starts. The app expects its runtime datasets and static assets under public/.
npm run typecheck
npm run test
npm run lint
npm run build
npm run test:e2e:chromiumUse npm run build:check to create a production build and check the bundle budget. Use npm run repo:check or npm run data:validate to validate packaged artifacts.
src/
app/ Application shell and routing
pages/ Home, Watch, Planner, Explore, About, Model, and 404 pages
features/ Map, planner, watch, location, and analyst features
shared/ Shared components, state, configuration, and data access
public/
data/ Forecasts, grids, activity, metadata, and locations
images/ Static illustrations and icons
spot-photos/ Viewing-location photography
docs/screenshots/ README page screenshots
scripts/ Build, test, and artifact-validation utilities
Important configuration lives in:
src/shared/config/appConfig.tsfor application and forecast defaultssrc/shared/config/dataPaths.tsfor runtime data pathssrc/shared/config/planner.tsfor planner behaviorvite.config.tsfor the frontend build
The public application reads packaged datasets from public/data, including activity summaries, expected counts, forecasts, forecast grids, recent sightings, population context, periods, metadata, places of interest, the grouped webcam inventory, and week-of-year historical smooth rasters used by the Planner. Keep temporal periods, H3 resolutions, model identifiers, and GeoJSON coordinate order consistent when refreshing these artifacts.
Forecast values should be interpreted as relative rankings across time and space. Reporting effort, access, weather, and sparse observations can all affect what is recorded and what can realistically be seen.
Forecast metadata is primed asynchronously after React starts. A missing or invalid metadata file must not prevent metadata-independent routes such as Home, About, Explore, or the 404 page from rendering. Forecast-owning pages handle their data loading and recovery locally. Failed metadata loads are retryable rather than permanently cached as rejected promises.
OrcaCast uses React Router for client-side navigation. src/shared/config/routes.ts is the source of truth for route paths, navigation labels, page metadata, error-boundary names, and navigation placement. App.tsx keeps only the exhaustive typed mapping from route IDs to lazy page components. The visible OrcaCast brand in the shared header always navigates to Home; map resets and other page actions belong to explicitly labelled controls.
Each route sets a distinct document title, description, Open Graph title, and Open Graph description during both direct loads and client-side navigation. Add new route knowledge to the typed registry rather than maintaining separate routing, metadata, navigation, documentation, or E2E lists. Unknown routes use the registry’s dedicated not-found metadata, and the smoke suite derives direct-load and Axe coverage from every navigable registry entry.
Hash navigation is handled after route transitions so links to an in-page target scroll after the destination has rendered. Prefer a dedicated registered route when content is a first-class page rather than an anchor within Home.
The shared information modal and navigation drawer provide initial focus, keyboard focus trapping, Escape dismissal, background inertness, and focus restoration. Serious and critical Axe violations—including color contrast—are blocking failures in the E2E smoke suite.
When adding routes or major UI states:
- Use semantic headings, landmarks, and labelled controls.
- Preserve visible keyboard focus and WCAG AA contrast.
- Register the route in
src/shared/config/routes.ts; the smoke suite automatically includes it in desktop and mobile direct-load, refresh, console, network, and Axe checks. - Verify dialogs retain focus and restore it to the opener when dismissed.
npm run buildDeploy the generated dist/ directory to a static host. Because OrcaCast uses client-side routing, configure the host to serve index.html as the fallback for every application route.
For Cloudflare Pages:
- Build command:
npm run build - Output directory:
dist - Node.js version: 18 or newer
- Production URL:
https://orcacast-public.pages.dev
GitHub Actions validates, builds, deploys, and smoke-tests OrcaCast. The CI build uploads one
checksummed production-dist artifact; preview, staging, and production jobs download those same
bytes rather than rebuilding them. A failed production smoke test rolls Cloudflare Pages back to
the previously successful production deployment.
Before enabling deployment jobs:
- Create
previewandproductionGitHub environments. - Add
CLOUDFLARE_API_TOKENandCLOUDFLARE_ACCOUNT_IDsecrets to both environments. Use a scoped token with Pages write access, not a global API key. - Add a repository variable named
PRODUCTION_URLcontaining the canonical HTTPS origin. - Disable Cloudflare Pages automatic production and preview Git builds so they cannot bypass CI.
- Enable the dependency graph, CodeQL, secret scanning, push protection, and validity checks.
- Protect
mainand require theci, dependency-review, CodeQL, and deployed-preview checks.
Browser-visible map keys are public configuration and must be restricted by domain, API, and quota
at their provider. Never place private credentials in a VITE_ variable.




