Skip to content

Show the Content pages that cite a dashboard in Analytics - #9558

Open
3mdistal wants to merge 8 commits into
mainfrom
alice/analytics-cited-in
Open

3mdistal wants to merge 8 commits into
mainfrom
alice/analytics-cited-in

Conversation

@3mdistal

@3mdistal 3mdistal commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Since #8937, an editor can paste an Analytics panel link into a Content page and keep a copy of that chart in the page. The dashboard never hears about it. Someone about to change or retire a dashboard can't see which weekly reviews, retros or plans quote its numbers, so they can break a page's story without knowing. A reader who lands on the dashboard can't find the write-ups that explain it either.

Approach

Each dashboard header in Analytics gets a Cited in menu. It lists the Content pages that hold a chart from that dashboard, most recently edited first, and only the pages the viewer can open. Each link opens the page in a new tab.

Content keeps a small index of which dashboards each page's charts come from: one row per page and dashboard in a new table, content_analytics_chart_citations. Content updates a page's rows in the same transaction that saves its body. Most save paths already run syncPrivateBodyReferences, which keeps a page's links to its private images and icons, so the update runs there. Six save paths skip that step and now update the rows directly: legacy edit-document, a collection row's primary Blocks field, collection block edits, form submissions, and row migrations and their rollback. Deleting a collection's primary Blocks property empties its rows' bodies, so it clears their rows too. Agents don't need to do anything extra: a chart an agent writes with edit-document is indexed just like one an editor pastes.

The index only narrows the search. When Analytics asks for a dashboard's pages, Content's list-analytics-chart-citations action:

  1. reads up to 1,000 candidate page ids from the index in one query, most recently edited first;
  2. keeps only the pages the caller can open (accessibleDocumentIds), before reading any title or body;
  3. drops trashed pages;
  4. checks each remaining body's chart tags for that dashboard's id, to confirm the page still holds one of its charts.

So a stale row never shows a page; it only costs a skipped check.

Analytics checks that the person can open the dashboard, then calls that action as them, over the same cross-app call Content uses to fetch charts (invokeAgentAction). On beta it calls beta Content's URL. Asking for "content" by name would reach production, the same problem #9301 fixes for Content's calls to Analytics. If Content can't answer, the menu says so, and the dashboard itself is unaffected.

What changed

Content

  • server/db/schema.ts, server/plugins/db.ts: the citations table and migration 142 (unique on page and dashboard, indexed by dashboard).
  • server/lib/analytics-chart-citations.ts: syncAnalyticsChartCitations makes a page's rows match the dashboards its new body holds charts from. When neither the old nor the new body has a chart tag, it returns after one substring check.
  • It's called from syncPrivateBodyReferences (server/lib/private-icon-references.ts), from accepting a suggestion that adds or removes a chart (server/lib/suggested-edits.ts), and from the six save paths above.
  • actions/delete-document-property.ts: deleting a primary Blocks property clears the rows of the pages it empties (clearAnalyticsChartCitations).
  • shared/analytics-charts-in-body.ts: analyticsChartDashboardIds finds the chart blocks in a body (code blocks don't count) and reads only each chart's dashboard attribute, not the rows it keeps. chartTagNamesDashboard is the list's quicker check: it scans the body's chart tags for one dashboard id. A tag written in a form the quick reader doesn't recognize goes through the full MDX parse instead.
  • actions/list-analytics-chart-citations.ts: the read-only action Analytics calls. Other apps can call it only for a signed-in person (publicAgent: { expose, readOnly, requiresAuth }).
  • scripts/guard-db-tool-scoping.mjs: keeps the new table out of the raw-database tools, like content_private_media_references.
  • The parity matrix and the document-editing skill mention the list action.

Analytics

  • server/lib/content-peer.ts: the lane-aware call to Content. It checks the shape of the answer and that each page link is an http(s) URL.
  • actions/list-dashboard-citations.ts: checks dashboard access, then returns { status: "ok", pages, more } or { status: "unavailable", reason }. It isn't an MCP tool; outside agents can call Content's action directly.
  • app/pages/adhoc/sql-dashboard/CitedInMenu.tsx, next to the annotations menu: it fetches only when opened, shows loading, empty, unavailable and "there may be more" states, and scrolls when long. Below 1280 px it shows only its icon, so the header doesn't grow past the screen; the label stays as the button's accessible name and tooltip. Strings are in all 11 locales.

Safety and operations

  • Migration: additive. It creates one table and two indexes and touches no existing table.
  • Cost on save: a page with no charts gets one substring check. A page with charts has its body split into blocks and each chart's dashboard id read, about 0.1 s for a 38 KB page; a few rows are then written inside the save's transaction, so a failed citation write fails the save. The first version parsed each whole chart tag, rows and all, which took 0.3 to 0.5 s per chart on every save.
  • Cost of opening the menu: with 56 cited pages it filled in within 0.65 to 0.96 s. The first version, which parsed every candidate page's charts in full, took about 38 s.
  • Access: Content returns only pages the caller can open, and Analytics checks the dashboard first. An editor could hand-write a chart tag naming any dashboard id. The page would then appear in that dashboard's list, but only to people who can already open the page.
  • Bounds: one list call reads at most 1,000 candidate ids in one query, checks access for 200 at a time and reads page bodies 25 at a time. It returns at most 50 pages and sets more when it stopped early or there were more than 1,000 candidates. Titles are cut to 500 characters without splitting an emoji, so a long title can't fail the whole answer.
  • Rollback: reverting removes the menu and the writes; the table stays, unused.

Verification

Run on throwaway boat.dev Linux machines against this branch, rebased on main at cb3d88c:

  • pnpm typecheck, oxfmt --check on the changed files, oxlint and pnpm guards: pass.
  • actions/analytics-chart-citations.db.test.ts (new; Content against a real database): all 12 tests pass. It checks that:
    • a page's rows follow its body through update-document, through edit-document with and without a revision, and through the shared save step;
    • the list shows only pages the caller can open and skips trashed pages and pages that no longer hold the chart;
    • the list finds the caller's page behind 201 newer pages they can't open, stops at 50 pages with more set, and shortens long titles without splitting an emoji.
  • actions/blocks-seeding.db.test.ts: deleting a collection's primary Blocks property clears the citations of the pages it empties.
  • server/lib/analytics-chart-sharing.test.ts covers the quick dashboard-id reader: one id per dashboard however many of its charts a page holds, a tag in another form read through the full parse, an earlier attribute that quotes a dashboard not mistaken for the real one, and tags with a bad or missing id or inside a code block skipped.
  • Analytics: content-peer.spec.ts, list-dashboard-citations.spec.ts and CitedInMenu.spec.tsx pass.
    • The peer test shows beta targets beta Content's URL, while production and local runs ask for "content" by name.
    • The menu test covers the fetch on open, the links, and the loading, empty, unavailable and "there may be more" states.
    • Analytics' whole suite passes (505 files).
  • Content's whole suite: 11,864 tests pass and one fails, the Discussion panel's "remembers the sort and a Page's filters" (CommentsSidebar.discussion.test.tsx). That test is flaky on main too: run five times at cb3d88c, it failed twice at the same step, and this PR changes nothing it loads. CI's Content DB tests pass.

Two CI checks fail for reasons outside this PR:

  • Fast tests (targeted lane 6): Core's tool-search benchmark scores MRR 0.864 against its 0.871 floor. Main at cb3d88c scores the same on a clean machine, and with or without this PR's two new actions every request ranks the same. #9550 restores it on main.
  • Content convergence (regular, gate off): "refreshing after a save was cut off" expects the toast "Action update-document failed: Failed to fetch". Since #9372 the client shows "Something went wrong. Try again." for that error, so the test's expected text is out of date. This check isn't required.

In a browser, with Content and Analytics running from this branch on one Linux machine (signed-out dev mode, demo data):

  • Pasting an Analytics panel link into a Content page kept the chart, and the dashboard's Cited in menu then listed that page. Its link opened the page in a new tab (noopener noreferrer).
  • A dashboard with no cited pages says so, and while Analytics couldn't yet reach Content, the menu showed its "unavailable" message.
  • With 55 more pages citing the dashboard, the menu shows the 50 most recently edited, scrolls, and ends with the "there may be more" note, in light and dark themes.
  • Keyboard: Enter opens the menu with the first page focused, Escape closes it and returns focus to the button without reopening its tooltip.
  • Header width: from 1280 px the button shows its label. At 1024 px, sidebar open, it shows only its icon, and the header fits on a built-in dashboard and on an editable one in view mode (see Known gaps for edit mode).

Not checked yet: the round trip on beta, which needs this deployed, and a second viewer's list in a browser (the database test covers who sees which pages).

Review focus

  • Does every way a page body gets saved update the index? The Builder and GitHub syncs don't; see below.
  • The order in list-analytics-chart-citations.ts: ids only, then accessibleDocumentIds, then titles and bodies.
  • The citation write runs inside each save's transaction, so a failure there fails the save. Is that the right trade against an index that can silently miss pages?
  • The quick attribute reader in shared/analytics-charts-in-body.ts (jsonAttribute): it must never name a dashboard the full parse wouldn't. Anything it doesn't recognize falls back to the full parse.

Known gaps

  • Pages that already held a chart before this ships appear after their next save. Charts reached Content on Nov 17, so few pages are affected. A backfill would mean scanning every page body.
  • Pages synced from Builder or GitHub don't update their rows when a sync rewrites them. A chart only gets into such a page through an edit in Content, which records it. If a sync removes the chart, the list's body check hides the page. The check doesn't tell a code block from the page, so a sync that leaves the chart's tag inside a code block would keep the page listed until its next save in Content.
  • The dashboard header already runs past the right edge of the screen on main at some widths with the sidebar open: by about 200 px at 768 px wide while editing a dashboard, and on a built-in dashboard below about 810 px. Cited in's icon adds 66 px there. While editing, between about 1024 and 1056 px, it now overflows by up to 32 px where main fits, partly hiding the agent button. Below 768 px Analytics hides the whole header, Cited in included, as before. Letting the header's buttons wrap or collapse is a change to every Analytics page, so it isn't in this PR.

🤖 Generated with Claude Code

Parsing a whole chart tag (its kept rows included) took 0.3-0.5 s per
chart, on every save of a charted page and for every candidate page the
Cited in menu checks: the menu took about 38 s with 56 cited pages.

Saving now reads only the dashboard attribute of each chart block (about
0.1 s for a 38 KB page body), and the list's per-page check scans the
body's chart tags for the dashboard id. A tag written in another form
still goes through the full MDX parse.
- Read the dashboard's candidate pages in one query instead of paging
  with an offset, which could skip a page when a citation was removed
  between batches. "more" is now set only when there are candidates
  past the 1,000 checked.
- Cut a long title on a UTF-16 boundary without splitting a surrogate
  pair, so a title ending in an emoji can't break the output schema's
  500-character limit and fail the whole list.
- Clear the citations of pages emptied by deleting a collection's
  primary Blocks property, so stale rows can't crowd real ones out of
  the 1,000 candidates.
- Format the sharing test.
@3mdistal
3mdistal marked this pull request as ready for review November 20, 2026 18:32

@builder-io-integration builder-io-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Builder reviewed your changes and found 2 potential issues 🟡

Review Details

Code Review Summary

PR #9558 adds a Content-side index of Analytics dashboard citations, synchronizes it on several document saves, exposes a permission-filtered Content action, and adds an Analytics menu that links to citing pages. The action-to-action design is generally sound: Analytics checks dashboard access before the peer call, Content filters candidate IDs through page access before reading titles or bodies, and cross-app responses and links are validated. This is high risk due to the migration and cross-app data-access boundaries.

Findings

  • 🟡 MEDIUM — Existing chart pages are not backfilled. The migration creates an empty citation index, so pages already containing chart blocks remain absent until saved again.
  • 🟡 MEDIUM — more can reveal hidden citation volume. It is derived from candidate rows including pages the caller cannot open.
  • 🟡 LOW — Some external-source body writes do not sync citations. Those pages can remain missing from the index after updates/imports.
  • 🟡 LOW — Citation re-check can count code examples. Its raw tag scan differs from the parser used to build the index.
  • 🟡 LOW — A parser exception is treated as no dashboard citation. That makes an unreadable tag indistinguishable from a valid tag without an ID.

The added tests cover core save, access, stale-row, and menu behavior, and all Analytics locales include the new strings. 🧪 Browser testing: Will run after this review (PR touches UI code).

Comment on lines +1805 to +1807
version: 142,
name: "content-analytics-chart-citations",
sql: `CREATE TABLE IF NOT EXISTS content_analytics_chart_citations (

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Migration leaves existing chart pages out of the citation index

Migration 142 creates an empty citation table without populating it from existing document bodies. Since the listing action searches this index first, pages that already contain AnalyticsChart blocks remain absent from “Cited in” until they are edited and saved again; add a reliable backfill or equivalent population step.

Fix in Builder

Comment on lines +139 to +141
return {
pages: pages.slice(0, MAX_PAGES),
more: pages.length > MAX_PAGES || candidates.length > MAX_CANDIDATES,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 More flag reveals inaccessible citation activity

candidates includes pages the caller cannot open, but more exposes whether the total exceeds MAX_CANDIDATES. A dashboard viewer can therefore infer that private pages cite the dashboard even when none of those pages are returned; avoid deriving a visible flag from inaccessible candidates.

Fix in Builder

@github-actions

Copy link
Copy Markdown
Contributor

Visual recap — generation failed

Recap authentication failed — PLAN_RECAP_TOKEN was rejected; it may be expired, revoked, or minted for another Plans app. Personal token: run npx @agent-native/core@latest connect <app-url> --client codex, then npx @agent-native/recap-cli@latest recap setup. Org service token: an owner/admin can mint a 10-year replacement with npx -y @agent-native/core@latest connect <app-url> --service-token <name> --ttl-days 3650. Update this repo's secret.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants