Skip to content

feat(core): add human-readable note attr to @slide-comment markers#67

Open
aggradon wants to merge 1 commit into1weiho:mainfrom
aggradon:feat/readable-comment-notes
Open

feat(core): add human-readable note attr to @slide-comment markers#67
aggradon wants to merge 1 commit into1weiho:mainfrom
aggradon:feat/readable-comment-notes

Conversation

@aggradon
Copy link
Copy Markdown

@aggradon aggradon commented May 6, 2026

Problem

Every comment added via the inspector is stored as a base64url-encoded payload in the TSX source:

{/* @slide-comment id="c-xxx" ts="ISO" text="eyJub3RlIjoiYmFyIHR..." */}

Agents (and humans) cannot read comments at a glance — they must regex-find → base64url-decode → JSON.parse → extract note. Search tools abbreviate the base64url to eyJub3...zIn0, making the comment invisible. This adds friction to every /apply-comments cycle.

Solution

Add a note="..." attribute with the raw, human-readable text:

{/* @slide-comment id="c-xxx" ts="ISO" text="<base64url>" note="bar too wide - make it smaller" */}
  • Agents can read comments directly — no decode step needed
  • Backwards compatibletext (base64url) preserved, note is optional
  • Safe escapingJSON.stringify handles ", \\, */, etc.

Changes

File Change
comments-plugin.ts Updated MARKER_RE regex, parseMarkers() fast path, marker generation, DELETE regex
comments-plugin.test.ts 3 new tests: direct read, special chars, legacy fallback
apply-comments/SKILL.md Updated regex, procedure, base64url section

Testing

  • pnpm test — 3 new parseMarkers tests pass
  • Local node_modules patched and verified with live dev server

Add a `note="..."` attribute to @slide-comment markers so agents and
humans can read comments directly from the source file without base64url
decoding. The `text` attribute (base64url payload) is preserved for
backwards compatibility.

- MARKER_RE regex: captures optional note attr group
- parseMarkers(): fast path reads note directly, falls back to decode
- Marker generation: includes note with JSON-string escaping
- DELETE regex: handles new format
- Tests: 3 new cases (direct read, special chars, legacy fallback)
- Skill: updated regex, procedure, and base64url docs
@vercel
Copy link
Copy Markdown

vercel Bot commented May 6, 2026

Someone is attempting to deploy a commit to the Yiwei Ho Team on Vercel.

A member of the Team first needs to authorize it.

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