Page Context for the Assistant

When someone opens your app inside Stardeck, Starcat sits in a sidebar next to it and can already see the page's address and title. Page context lets a page hand Starcat more: a short label for what's on screen, structured details, and instructions for how to help on this page. The user can then ask "remind this customer about their overdue invoice" without first describing what they're looking at.

Page context is set in your app's code. Ask your coding agent to add it to the pages where people are likely to ask for help: @stardeck-customer-apps/client-utils ships a SKILL.md that tells the agent how to write it and where it's worth adding. If you build in the browser, ask Starcat Developer in the app's Build tab. Page context only has an effect when your app runs inside the Stardeck shell. Outside the shell it does nothing, so the same code is safe to ship everywhere.

What It's ForCopy Anchor Link

A few examples of context a page might declare:

• An invoice detail page sets the label to Invoice #1042 (overdue) and instructs Starcat to offer drafting a payment reminder.
• A customer record page shares plan: pro, MRR: $240, 14 days overdue as details, so answers reference the real numbers.
• A dashboard tells Starcat which metric the user is focused on and what actions make sense from here.

Adding ItCopy Anchor Link

Page context is set with the useStardeckPageContext hook from @stardeck-customer-apps/client-utils (included in every app). Call it from any page or component and pass what you want Starcat to know:

import { useStardeckPageContext } from "@stardeck-customer-apps/client-utils";

function InvoicePage({ invoice }) {
  useStardeckPageContext({
    label: `Invoice #${invoice.number}${invoice.isOverdue ? " (overdue)" : ""}`,
    details: `amount: ${invoice.amountFormatted}; status: ${invoice.status}`,
    instructions:
      "This page is about a single invoice. If it's overdue, offer to draft a payment reminder email to the customer.",
    suggestedPrompts: [
      {
        label: "Draft a payment reminder",
        prompt: "Draft a friendly reminder email for this overdue invoice.",
      },
      { label: "Summarize this invoice", prompt: "Summarize this invoice and its payment status." },
    ],
  });

  return /* ...your page... */;
}

Every field is optional:

The context updates whenever the values change and clears automatically when the user navigates away from the page or the component unmounts. Pass null to clear it yourself.

Sections and dialogsCopy Anchor Link

A layout, a page and an open dialog can each set their own context. Pass a scope as the second argument, named after the route ({ scope: "menu" } in the menu layout, { scope: "menu/items" } on the items page). Starcat reads the parent before the child, and closing a dialog clears only the dialog's context. This needs client-utils 4.5.0 or later; older versions ignore scope.

What the User SeesCopy Anchor Link

Page context is visible, not hidden. Whenever a page is sharing context, an indicator appears in the app shell header when your app is open, and in the sandbox preview toolbar while you build. The user can click it to see exactly what the page is sharing: the label, details, instructions, and any suggested prompts. Nothing is sent to the assistant that the user can't inspect.

In the app shell, the suggested prompts are one-tap buttons: tapping one opens Starcat and asks that question for the user. (In the sandbox preview they show as plain examples, since there's no assistant attached to the preview.) Use them to point people at the most useful things to ask on each page.

How the Assistant Uses ItCopy Anchor Link

The context is attached to the user's next message and given to Starcat as background on what they're looking at. Instructions are treated as advice from your app, not as commands. Starcat considers them but won't follow page-supplied text that conflicts with its own rules. Use them to steer toward helpful actions, not to try to override how the assistant behaves.

Common QuestionsCopy Anchor Link

Does this work when my app runs on its own domain, outside Stardeck? The hook only has an effect inside the Stardeck shell. On a standalone deployment it's a no-op, so you can leave the calls in place.

Will old versions of my app break? No. Page context is additive. Apps that haven't been updated simply don't send it, and the indicator stays hidden.

Can the user turn it off? The user always sees what's being shared via the indicator and can read it in full. The page decides what to share; the platform makes it transparent.

Is the page's full text shared too? That's a separate, user-controlled feature: the Include current page content toggle in the Starcat sidebar. Page context is what your page declares on purpose; page content is the on-screen text the user opts to share per message. See Starcat.

NextCopy Anchor Link