Skip to content

docs: full-width overview hero with a live, hoverable memory constellation - #5436

Merged
nicoloboschi merged 3 commits into
mainfrom
docs-overview-hero-screenshot
Oct 8, 2026
Merged

nicoloboschi merged 3 commits into
mainfrom
docs-overview-hero-screenshot

Conversation

@nicoloboschi

@nicoloboschi nicoloboschi commented Oct 8, 2026 •

Copy link
Copy Markdown
Collaborator

What

The docs overview hero now shows the control plane's memory constellation running live — hover, pan, zoom — instead of a screenshot of it.

Two commits:

  1. Full-width two-column hero (copy left, product right), flow moved under How It Works.
  2. The product side becomes the real Constellation component over a synthetic bank.

How

  • src/components/constellation/Constellation.tsx is a near-copy of hindsight-control-plane/src/components/constellation.tsx. Differences:
    • next-intl → a local string table (same keys as messages/en.json)
    • dark mode reads Docusaurus's data-theme instead of a dark class
    • the HUD stats line and the "scroll to zoom" hint are skipped below 760px wide — at the hero's width they ran into the legend and under the toolbar
    • allowFullscreen prop (default true), off in the hero: from inside the band's stacking context (isolation: isolate) the fixed overlay renders behind the navbar and sidebar
  • MemoryConstellation.tsx calls it the way the Memories view did: one flat field, coloured by mention recency, observations sized by source facts, same link colours.
  • constellation/mock-bank.ts builds a deterministic (seeded) bank with the same rules as GET /graph (MemoryEngine.get_graph_data):
    • semantic / temporal / caused_by links between facts (retain writes only caused_by)
    • observations have no links of their own; they inherit their sources' links and entities, and link semantic to observations sharing a source
    • entity links derived from shared entities, capped at 10 neighbours
    • node colour by entity count, labels cut at 30 chars
  • @chenglou/pretext added to the docs package (the component's only dependency).
  • Softer shadow on the hero frame; static/img/hindsight-ui.webp removed (no longer referenced).
  • The canvas is wrapped in role="figure" with an aria-label (the screenshot had alt text); Share export loads the logo from the docs' /img/logo.png.

Verified

  • docusaurus build passes; ./scripts/hooks/lint.sh passes.
  • Checked in light and dark, hover tooltips and neighbour highlighting.
  • scripts/check-mock-bank.mjs (now part of the docs build) guards the mock bank: every link joins two real memories with a known type and a 0..1 weight, none isolated, observations carry a source count, output is deterministic. Fails loudly on a bad observation source index (verified).

Known

  • The component fits the field to the frame's shorter side, so at the hero's 420px height it starts zoomed out (~0.23x) and shows no labels until you zoom in. Fixable with a taller frame or a starting-zoom prop.
  • Constellation.tsx is a copy (~1.7k lines); control-plane changes need re-syncing by hand.

…orks

The hero's memory-graph clip is replaced by a screenshot of the control
plane, and the band is now a two-column landing layout — copy left, product
right — that runs the full width of the window with the doc sidebar starting
underneath it. At 1140px the screenshot was a thumbnail of a UI whose whole
point is that you can look at it.

The sidebar is a sibling of <main>, so it cannot be moved by anything nested
inside main: HomeHero reports the band's height in --hs-hero-height and
custom.css drops the sidebar by it, matching the page on the doc-id class the
theme already puts on <html>.

HomeFlow is unchanged but now opens "How It Works" instead of sitting
directly under the hero, so the hero is the whole first screen. The root page
is served from the versioned copy, so both index.mdx files move it.
Replaces the hero's static control-plane screenshot with the control plane's
own Constellation component, running over a synthetic bank.

- constellation/Constellation.tsx is a near-copy of
  hindsight-control-plane/src/components/constellation.tsx: next-intl is a
  local string table, dark mode reads Docusaurus's data-theme, the HUD and
  instructions are skipped on narrow canvases (they overlapped the legend and
  toolbar), and Fullscreen can be turned off (it renders behind the navbar
  from inside the hero band's stacking context).
- MemoryConstellation calls it the way the Memories view did: one flat field,
  coloured by mention recency, observations sized by source facts.
- constellation/mock-bank.ts builds a deterministic bank with the same rules
  as GET /graph: semantic/temporal/caused_by links between facts, observations
  inheriting their sources' links and entities, derived entity links capped at
  10 neighbours.
- Softer shadow on the hero frame; drops the now-unused hindsight-ui.webp.
- Share export: load the logo from /img/logo.png — the docs site has no
  /logo.png, so exported SVGs silently lost it.
- Accessibility: the canvas had no accessible name (the screenshot had alt
  text); wrap it in role="figure" with an aria-label (figure, not img, so
  the Share/Pause buttons inside stay reachable).
- Overview text no longer calls the sample graph "one bank's".
- New scripts/check-mock-bank.mjs, run by the docs build: every link joins
  two real memories with a known type and a 0..1 weight, no memory is
  isolated, observations carry a source count, and the bank is
  deterministic. Transpiles the .ts with the docs' own TypeScript, since CI
  runs Node 20.
- MemoryConstellation: drop the one-caller height prop for a constant;
  keep the docs components' quote style.
- Constellation.tsx: every docs-only difference from the control plane's
  copy is now marked "Docs-only"; the header no longer claims the rest is
  identical.
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.

1 participant