Skip to content

feat(reports): add Cursor Canvas report route - #49

Merged
phodal merged 2 commits into
mainfrom
feat/cursor-canvas-report
Aug 1, 2026
Merged

feat(reports): add Cursor Canvas report route#49
phodal merged 2 commits into
mainfrom
feat/cursor-canvas-report

Conversation

@phodal

@phodal phodal commented Aug 1, 2026

Copy link
Copy Markdown
Member

Summary

Cursor gains a host-native Canvas report rendered with the public cursor/canvas
SDK. Cursor session scans now project any workspace-scoped native
context-usage-*.canvas.data.json snapshot into a Context Window section of the
complete report, with raw item text always omitted and a missing snapshot kept
explicitly unobserved rather than reported as zero usage.

Open decision for reviewers. The originating request was narrower: "a Canvas
for cursor.app that shows the Context Window". This PR delivers the complete
Better Harness report with Context Window as one of eight sections, and it also
switches Cursor's default output route from portable HTML to Canvas. That
route switch is a user-visible behavior change that the original request did not
ask for. If the intended scope is a standalone Context Window Canvas with Cursor
keeping its HTML default, this branch should be reworked rather than extended.

Why

  • Issue/Story: none. Spec-backed work; no tracker id exists for it, so this is not
    linked to an issue.
  • User or maintainer outcome: Cursor users get the same durable, complete report
    experience Qoder users already have, plus visibility into what is consuming
    their context window — bounded to evidence Cursor itself materialized.

Traceability and Scope

  • Spec/ADR, if applicable: docs/specs/2026-08-01-cursor-canvas-report.md;
    docs/adrs/directory-structure.md records the new
    templates/reporting/cursor-canvas.md owner.
  • Acceptance criteria addressed: AC-1 through AC-7 of that spec.
  • Canonical owners changed: scripts/session-analysis/platforms/cursor.mjs
    (Context Usage discovery/projection), scripts/harness-analysis/ (renderer,
    validator, schema, render routing), templates/canvas/better-harness-cursor.canvas.tsx,
    templates/reporting/cursor-canvas.md + routing.md, skills/better-harness/SKILL.md.
  • Explicit non-goals: reproducing Cursor's proprietary Context Usage
    implementation or template; decoding store.db; making Canvas generation a side
    effect of every JSON command; refactoring the existing Qoder Canvas template.

Change Type

  • Feature
  • Bug fix
  • Tests only
  • Documentation/community
  • Refactor with no intended behavior change
  • Dependency, packaging, or infrastructure

The bug-fix commit resolves a privacy-boundary leak found while adding the test
coverage for the feature commit: contextItemLabel fell back to the native
source.label even after safeContextSource had rejected that source for living
outside the workspace, so an excluded file could still name a Context Window row.

Test and Review Evidence

Check Result
npm test 1,061 passing, 0 failing (was 1,051 on main; +10 new)
npm run pack:verify pass — npm 373 entries, runtime zip 396 entries
node --test test/doc-link-graph.test.mjs 6 passing; generated routing graph current
node --test test/cursor-canvas-report.test.mjs 10 passing (new suite)
harness render --mode cursor-canvas --validate --json status: pass across all 5 Cursor checks; artifacts exactly findings.json, canvas.json, report.canvas.tsx; sole import cursor/canvas; TSX transform succeeded

Manual or visual evidence:

  • Every symbol imported by the template (23 components/hooks) and all three
    dispatched action types (newComposerChat, openFile, openAgent) were checked
    against the shipped Cursor SDK type declarations in
    Cursor.app/.../agent-sdk/cursor/canvas/*.d.ts, including prop-level names such
    as UsageBar.total/segments/topLeftLabel, Table.emptyMessage, and
    Text.truncate.
  • Real Cursor scan of a workspace with an observed native snapshot:
    56,860 / 300,000 tokens, 19% full, 7 categories, 119 bounded items; verified no
    raw text field, no absolute-path labels, and no parentId in the projection.
  • Real Cursor scan of an unobserved workspace: status: unobserved with
    exists: false and the normal missing-optional-root warning.
  • Cursor 3.13.10 opened the generated managed Canvas and rendered the overview,
    Fluency chart, AI Agent Practice, Context Window, findings, and evidence sections.

Risk and Recovery

  • Compatibility and cross-platform impact: Cursor's default report route changes
    from HTML to Canvas    , so Cursor runs no longer emit report.md/report.html by
    default. Path handling uses path.isAbsolute/relative/sep and the existing
    Windows file-identity helpers, but the runtime verification above was performed on
    macOS only; Windows and Linux rest on CI.
  • Package, plugin, schema, or generated-file impact: two new shipped files under
    scripts/harness-analysis/ and templates/, both covered by pack:verify.
    summary.contextUsage is a new additive, optional field in the report contract;
    existing Qoder, Markdown, and HTML routes are untouched. JSON analysis stays
    write-free unless an explicit output option is passed.
  • Rollback or recovery path: revert both commits. The new mode is additive, so
    removing cursor-canvas from the mode set restores Cursor's HTML route.
  • Residual risk or unverified boundary:
    • The scope/default-route question above is unresolved.
    • item.source is only retained when the referenced file is inside the
      workspace. On the one real snapshot available, 0 of 119 items qualified (its
      files belonged to a sibling repository), so the Context Window openFile action
      is proven by unit fixtures rather than by live data.
    • Cursor's native snapshot schema and public Canvas SDK are both external and may
      change; the reader fails closed on malformed snapshots and avoids private
      command ids and internal imports.

AI Involvement

  • Level: Generated.
  • Human review and validation: the maintainer reviewed the findings from an
    evidence-based review pass and directed the follow-up fixes; the automated checks
    and real-workspace scans in the table above were executed and their output
    inspected. The scope question is deliberately left to human decision and is not
    resolved here.

Checklist

  • I followed AGENTS.md, CONTRIBUTING.md, and the relevant canonical-owner guidance.
  • The change is focused and does not include unrelated local or generated state.
  • Tests and documentation match the behavior actually delivered.
  • Markdown links were checked when documentation moved or changed.
  • Cross-platform behavior was considered for Windows, macOS, and Linux.
  • Package/runtime verification was run when shipped files or dependencies changed.
  • User-facing or compatibility changes are recorded in CHANGELOG.md.
  • I have the right to contribute this work under the repository's MIT License.

CHANGELOG.md is intentionally left untouched: AGENTS.md forbids proactively
editing release metadata. The Cursor default-route switch does warrant a changelog
entry — please confirm the scope decision first, then say the word and I will add it.

phodal and others added 2 commits August 1, 2026 15:03
@phodal @Qoder-AI
feat(reports): add Cursor Canvas report route
090fff7 
Render the complete Better Harness report inside Cursor with the public
`cursor/canvas` SDK, and surface any workspace-scoped native Context Usage
snapshot as the Context Window section of that report. Cursor session scans
now project bounded token, category, and item metadata from Cursor's own
`context-usage-*.canvas.data.json` files while omitting raw item text, and a
missing snapshot stays unobserved instead of being reported as zero usage.

`harness render --mode cursor-canvas` writes a deterministic `findings.json`,
`canvas.json`, and `report.canvas.tsx` bundle, then validates the split data
contract, module boundaries, required report sections, public action bindings,
and the final TSX transform. This also moves Cursor's default output route
from portable HTML to the host-native Canvas, so the adapter matrix, report
routing, skill routing, and bilingual entrypoints are updated to match.

The intent, acceptance scenarios, and risks are recorded in
docs/specs/2026-08-01-cursor-canvas-report.md. Validated with npm test
(1051 passing), npm run pack:verify, and a real Cursor scan followed by a
validated cursor-canvas render against an observed native snapshot.

Co-authored-by: QoderAI <qoder_ai@qoder.com>
@phodal @Qoder-AI
fix(cursor): keep excluded context files out of report labels
f5224b6 
`contextItemLabel` fell back to the native `source.label` even when
`safeContextSource` had rejected that source for living outside the workspace,
so a file the boundary just excluded could still name a Context Window row.
Only an admitted source may label an item now.

Report the `cursor-context-usage` source from a materialized snapshot file
instead of its parent `canvases` directory, which can exist while holding no
evidence. A workspace without a snapshot now reports `exists: false` and raises
the normal `missing-optional-root` warning rather than claiming a present source
next to an unobserved projection. Drop the unresolvable `parentId` projection and
its schema slot, since native parent ids name synthetic group nodes that are
absent from `items` and no reader surface consumed the field. Give each Canvas
mode its own analyzer companion filename so the Cursor route no longer borrows
the Qoder constant.

Add `test/cursor-canvas-report.test.mjs` covering the bounded projection, the
workspace source boundary, the unobserved and fail-closed paths, the snapshot
presence contract, the Context Usage schema bounds, the renderer, the validator,
and a `--mode cursor-canvas --validate` run. The label leak surfaced only while
writing that coverage. The per-route artifact inventory stays asserted in
`templates/reporting/routing.md`, which owns it, because the root Skill sits
against a hard 12,000-byte prompt budget.

Validated with npm test (1,061 passing), npm run pack:verify, and real Cursor
scans of both an observed native snapshot and an unobserved workspace.

Co-authored-by: QoderAI <qoder_ai@qoder.com>
@phodal
phodal merged commit 81d3517 into main Aug 1, 2026
4 checks passed
@phodal
phodal deleted the feat/cursor-canvas-report branch August 1, 2026 09:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@phodal