API reference

Name: Cairn
Author: theartisticprogrammer

Every export.

@cairnkit/core

Framework-free engine. Zero runtime dependencies.

Prop	Type	Default	Description
`defineAnchors(registry)`	`<T>(T) => T`	—	Declares the anchor registry. Identity at runtime; exists for type inference.
`anchor(id)`	`(id) => props`	—	Props object to spread onto an element.
`anchorSelector(id)`	`(id) => string`	—	The CSS selector for an anchor, escaped.
`resolveAnchor(id, doc?)`	`(id) => HTMLElement \| null`	—	Finds the visible element for an anchor. Returns null on the server.
`defineFlow(flow)`	`(TourFlow) => TourFlow`	—	Declares a flow.
`createFlowRegistry(flows)`	`(TourFlow[]) => Registry`	—	Builds an id → flow map.
`getFlow(registry, id)`	`(...) => TourFlow \| null`	—	Looks a flow up by id.
`resolveResumeStep(flow, path, i)`	`(...) => number \| null`	—	Where to resume when the user is ahead. Pure, testable.
`decideForRoute(flow, path, i)`	`(...) => RouteDecision`	—	handoff / pause / resume / none, in that order.
`createTourStore(options)`	`(...) => TourStore`	—	Observable store, useSyncExternalStore-ready.
`localStoragePersist(key?)`	`(key?) => PersistAdapter`	—	Default persistence. Progress must survive a page transition.
`emitTourEvent(name)`	`(name) => void`	—	Signal from your app that a step is waiting on.
`onTourEvent(name, fn)`	`(...) => () => void`	—	Subscribe. Returns an unsubscribe.
`readRect / rectsEqual`	`helpers`	—	Measure and compare a target rect.
`watchForAnchor(id, ms, cb)`	`(...) => () => void`	—	Wait for a late-mounting anchor.
`scrollAnchorIntoView(el)`	`(el) => void`	—	Reduced-motion aware.

Key types

TourFlow · TourStep · AdvanceRule · Placement · AnchorId
CairnRegister · RegisteredAnchor · RegisteredFlowId · RegisteredEvent
CairnEvent · CairnEventHandler · TargetRect · TourStore · PersistAdapter

@cairnkit/react

Headless bindings. No styling.

Prop	Type	Default	Description
`<CairnProvider>`	`component`	—	Mounts the runtime. Props: flows, router, translate, onEvent, onNotice, store, mobileBreakpoint.
`useTour()`	`hook`	—	The controller — flow, step, rect, element, status, advance, back, skip, start, stop.
`useTourState(selector)`	`hook`	—	Subscribe to a slice of store state.
`useStepCopy(flow, step)`	`hook`	—	Resolves title and body, inline or via translate.
`useTourDeepLink(param?)`	`hook`	—	Starts a flow from ?tour=. Each value honoured once.
`useCairn()`	`hook`	—	Raw context — flows, router, store.
`<TourAnchor id>`	`component`	—	Escape hatch for components that swallow props.

@cairnkit/ui

Prebuilt overlay. Plain prefixed CSS, light and dark.

Prop	Type	Default	Description
`<CairnOverlay>`	`component`	—	Spotlight plus tooltip card. Props: labels, mobileBreakpoint, onNotice.
`<TourLauncher>`	`component`	—	The launcher. Props: flowId, label, position, pulse, icon, className.
`<Spotlight>`	`component`	—	Scrim and cutout only.
`<StepCard>`	`component`	—	The card only.
`<Launcher>`	`component`	—	Presentational launcher, unbound to a flow.
`<ProgressRail>`	`component`	—	Segmented step progress.
`@cairnkit/ui/styles.css`	`stylesheet`	—	Import once. Required for the prebuilt components.

@cairnkit/next

Prop	Type	Default	Description
`useAppRouterAdapter()`	`hook`	—	App Router adapter.
`usePagesRouterAdapter()`	`hook`	—	Pages Router adapter.

@cairnkit/cli

Prop	Type	Default	Description
`cairn check <dir>`	`command`	—	Static drift check. Exits 1 on any finding.
`auditFlow(page, opts)`	`function`	—	Drives one flow in a browser and reports per-step.
`auditFlows(page, list)`	`function`	—	Several flows; throws one readable error if any fail.