> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puntego.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guide Tools SDK

> Drive the guide from your own app code — point, highlight, run tours, register targets, and report outcomes through window.Puntego.

Use `window.Puntego` when your app already knows the right target or workflow and wants the guide to show it without waiting for a model turn. This is the imperative side of the guide: you call a method, the guide points, highlights, scrolls, or walks a tour right away.

Importing `@puntego/embed` augments the global `Window`, so `window.Puntego` is fully typed in TypeScript. The methods below are part of that typed surface unless a section says otherwise.

<Note>
  Call these methods after the runtime is ready. Wait for the `ready` event (or `whenPuntegoReady` from `@puntego/embed/loader`) before driving the guide, since `window.Puntego` is only present once the boot script has mounted.
</Note>

## Point, highlight, and scroll

These three single-shot methods cover most "show the visitor this element" cases. They run synchronously and return `void`, so there is nothing to await.

```ts theme={null}
window.Puntego.point('#pricing-growth', 'Growth plan');
window.Puntego.highlight('#pricing-growth', 'Growth plan');
window.Puntego.scrollTo('#checkout-summary', 'Checkout summary');
```

Pass a CSS selector, an element, or a target object. The optional second argument is the caption the guide shows next to the cursor.

## Show multiple markers

Use `markers` to label several elements at once — for example, to annotate a pricing grid or a multi-step form.

```ts theme={null}
window.Puntego.markers([
  { target: '#plan-free', label: 'Free' },
  { target: '#plan-growth', label: 'Growth' },
]);
```

## Run a guided tour

Use `tour` to chain steps into a single narrated sequence. Each step names a target and a step type (`point`, `scroll`, `spotlight`, or `caption`).

```ts theme={null}
window.Puntego.tour({
  title: 'Set up billing',
  steps: [
    {
      narration: 'Start by choosing the right plan.',
      target: '#pricing-growth',
      type: 'point',
    },
    {
      narration: 'Then review the checkout summary.',
      target: '#checkout-summary',
      type: 'scroll',
    },
  ],
});
```

## Use the control namespace

The same controls are mirrored under `window.Puntego.control` for product-owned helpers that want a stable namespace. The visual methods (`point`, `caption`, `highlight`, `scrollTo`, `markers`, `tour`) return `void`. Only `speak` is asynchronous, so it is the one to await.

```ts theme={null}
window.Puntego.control.point('#pricing-growth', 'Growth plan');
window.Puntego.control.caption('Compare the plans before upgrading.');

await window.Puntego.control.speak('Compare the plans before upgrading.');
```

## Register stable targets

Register stable IDs instead of relying on brittle selectors. Registered targets survive markup changes and let you constrain exactly which actions the guide may run against an element.

```ts theme={null}
window.Puntego.registerTarget('#pricing-growth', {
  id: 'pricing-card-growth',
  allowedActions: ['point', 'spotlight', 'scroll'],
  description: 'Growth plan pricing card',
  route: '/pricing',
});
```

Call `unregisterTarget('pricing-card-growth')` when the element leaves the page so the guide stops resolving it.

## Report workflow outcomes

When your app owns the state transition — a plan upgrade, a form submission, a booking — report the outcome so owners can see what happened. `reportWorkflowResult` is asynchronous, so await it.

```ts theme={null}
await window.Puntego.reportWorkflowResult({
  workflowId: 'billing-upgrade',
  actionId: 'select-growth-plan',
  status: 'completed',
  durationMs: 4200,
});
```

Puntego records each SDK action proposal and result as an outcome trace for owner review in the dashboard. A reported result is a record of what the guide did — it does not edit your action manifest or feed an automated learning loop.

## Advanced runtime helpers

The runtime also exposes `getPageContext()` and `locateTarget()` for apps that need to inspect what the guide can currently see before driving it. These are runtime-only helpers: they are not part of the typed `window.Puntego` surface, so a TypeScript consumer needs a cast to call them.

```ts theme={null}
const control = window.Puntego.control as any;

const page = control.getPageContext();
console.log(page.captureContext.targets[0]?.center_viewport);

const target = control.locateTarget('#pricing-growth');
if (target) {
  console.log(target.gp_id, target.computed_name, target.bbox_viewport);
}
```

<Info>
  Because these helpers are not typed, their return shapes may evolve. Treat them as advanced inspection tools rather than a stable contract, and prefer the typed methods above for production flows.
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="SDK reference" icon="book-open" href="/sdk-reference">
    The full typed surface for `window.Puntego` — every method, event, and option in one place.
  </Card>

  <Card title="Verified Actions" icon="shield-check" href="/verified-actions">
    Let the guide read or change a business object after policy checks, with confirmation and audit logging.
  </Card>
</CardGroup>