pessimistcamellia/proto-note

Prototype Change Annotation Layer (proto-note)

Overlay a "development perspective change guide" on single-file HTML prototypes: a fixed dark annotation bar on the right (module checklist + annotation cards) ↔ page anchor points + canvas connectors; bidirectional hover/click locators; annotation cards with SDD deep links.

Installation and Directory

# Personal skill (recommended)
git clone https://github.com/pessimistcamellia/proto-note.git ~/.cursor/skills/proto-note

# Or within a project
git clone https://github.com/pessimistcamellia/proto-note.git .cursor/skills/proto-note

You can also copy the entire directory to the above paths. Directory structure:

proto-note/
├── SKILL.md
├── assets/diff-annotator.js      # Annotation engine (inline entire file into the prototype; do not alter logic)
├── references/changeset-schema.md
├── docs/screenshots/             # README screenshots
└── scripts/deploy_github.sh      # GitHub Pages alternative deployment

Environment Dependencies

Capability	Tool	When Missing
Tech stack / source code location	codewiki MCP (or equivalent code search)	Restore using online URL + source repo + browser DOM
SDD deep link	lark-cli (Feishu)	Manually fill document URL and section blockId; if not using Feishu, link to the corresponding section anchor
Pixel-level calibration	Browser DevTools / chrome-devtools MCP	Manually open the online page and compare
Deployment	Intranet static hosting (preferred)	Personal GitHub Pages (deploy_github.sh, requires gh authorization)

If the team has additional front-end specification skills (e.g., selection whitelist, component library usage), read them as needed before production; otherwise, rely on the target repository's source code and team documentation.

Default Plan: Component Library & Publication Priority

Execute in priority order; fall through to the next level only if the preceding one is unavailable. The last level is the default fallback:

1. Component library / specification (preferred): Use the actual component library and specification used by the target production system (compare with source code / DOM / team specification skill). Do not switch libraries without justification.
2. Publication address (preferred): If intranet static hosting (or a team-agreed intranet address) is available, publish to the intranet first.
3. Default fallback: If the real component library/specification cannot be obtained, or due to permissions, network, intranet unreachability, etc. → Component selection can follow a general approach (still maintaining a single-file interactive HTML); publish to the user's personal GitHub repository (Pages). Before deployment, confirm gh authorization; if unauthorized, communicate with the user first and do not push to a private repo without consent.

Product Rules

1. Three-level change + type: Page / Module / Field; types include addition, text change, enum, logic, flow, deletion. Avoid vague labels like "added."
2. Hidden by default, module toggling: Annotations are not displayed on open; toggle by page::module; state goes into localStorage. Missing keys for newly added modules default to true (visible), do not inherit hidden state from "any toggle previously turned off"; dirty state is cleared by upgrading the LS_KEY version.
3. Only link to SDD, do not display PRD: Annotation cards use SDD document URL#blockId.
4. Information conciseness: Annotation bar has no version numbers/baselines/operation instructions; desc only contains conclusions.
5. Click must be effective: Toggling a module immediately switches the view + scrolls + pulse locates.
6. Review state only in the annotation bar: Normal/empty/error states go in demoControls; actual business tabs remain in the business page.
7. Provide reproducible examples for input branches: examples must match fixtures; avoid placeholder dummy values.
8. Annotation bar does not obstruct content: Do not compress business layout; use a spacer to extend scrollWidth for horizontal scrolling to see the full right side. Do not only add body padding-right or modify the business root width.
9. Component library & specification must prioritize the real production environment: If restoration is possible, it must be done (see "Default Plan" level 1). Using the same component library is not the same as restoration—skeleton, column sets/column widths, frozen columns, cell structure, action column layout, custom class names, and key styles must be compared with the online DOM/source code; compare screen by screen before delivery. Only when the real component library/specification cannot be obtained, allow generic component fallback.
10. Publish priority: intranet first, otherwise personal GitHub: If an intranet address is available, use it first; when unavailable, publish to personal GitHub Pages (see "Default Plan" levels 2–3).
11. "Before" = current online status: For additions, write "This page/module/function/field does not exist"; do not write differences relative to the previous version demo; online additions must not be missed.
12. No UI landing point, no connector: For pure process/linkage changes, set target: null, no anchor point; the card goes under "Processes & Linkages · Page Not Visible" and is placed at the end of the changes.
13. Changes within pop-ups: Clicking an annotation card must first open the pop-up via DIFF_HOOKS.locate, then connect the connector; anchor/connector z-index must be higher than the pop-up (engine uses the 9000 range).
14. Pop-ups scroll with page horizontal and vertical scrolling: When the annotation bar is open, the pop-up container translates with (-scrollX,-scrollY) (handled by the engine); do not lock scrolling to avoid this.
15. Downloadable items must be in the correct format: Templates/receipts must have the same format and structure as the real business (e.g., dual-sheet must be real .xlsx), do not use CSV as a substitute.
16. Create separately for each platform and link them: For admin backends, C-end, etc., create separate HTML files by system boundary; a unified menu indicates "Platform · Page"; for cross-page data, simulate write/read/start-stop/exceptions.
17. Annotation cards must be able to jump to SDD: When an SDD is available, each change (or its feature point) must configure sdd.section + blockId; the card renders a deep link; clicking should open the corresponding section, not just display the section name.

Display Layer Specification (Engine Built-in, Do Not Revert)

• Right annotation bar: Dark navy blue, width 360px, collapsible into a floating entry point.
• Horizontal scrolling: Measure business width using document.body.scrollWidth (spacer is absolute and not included in this value); do not hide the spacer before measuring. Restore scrolling with behavior:"instant" to avoid conflicts with scroll-behavior:smooth.
• Anchor points: Document coordinates position:absolute, pinned to the target's top-left corner; do not use fixed with scroll chasing; hide occlusion using elementFromPoint.
• Connectors: No lines by default; only draw one line on hover/fix; fixed state takes precedence over hover state; starting point uses real-time rect.
• Annotation card: Number + title + type·level + conclusion + before/after + SDD; may include examples.
• Demo area: Segmented control at the top of the annotation bar → DIFF_HOOKS.setDemoState.

Tech Stack Restoration (Step 0)

Execute according to the "Default Plan": restore when possible; if not, document the reason and proceed with free selection fallback.

1. User does not provide an online URL → first remind them; if still none, search the system/routes/source code on your own.
2. Use codewiki (or source code search) to confirm: framework, component library, routes → page files, key template fragments; if needed, check the freshness index and calibrate with online DOM.
3. Prefer the real component library and specification from the target repository; new controls follow the existing types/sizes/arrangements of that page. Using the same component library is not the same as restoration—skeleton, column sets/column widths, frozen columns, cell structure, action column layout, custom class names must be compared with online DOM/source code.
4. If a team specification skill exists, follow it; otherwise, follow the target repository and documentation.
5. When pixel-level or search information is insufficient: Open the online page and capture mounting methods, component class names, table column widths/frozen columns, action column structure, and custom computed styles.
6. Output remains a single-file HTML; if the same framework/component library can be introduced via CDN, do so. If the entire page cannot be restored, freely use common component libraries to complete the interactive prototype and note the "Reason for non-restoration" in the delivery notes.
7. Publish: If an intranet static address exists, upload there first; otherwise, after obtaining the user's GitHub authorization, use deploy_github.sh to publish to a personal repository.

Common pitfalls: Do not set an excessively wide min-width on the outer container that locks the table (this loses internal horizontal scroll and fixed columns); use position:fixed for the unified menu top bar to avoid a broken top bar when horizontally scrolling on a wide page.

Multi-Page / Multi-Platform & Data Linkage

1. First list a matrix: Platform/System → Page → Key States → Upstream/Downstream Data; separate files for different tech stacks; do not merge forcibly.
2. Unified menu: named "Platform · Page", current page highlighted; menu itself is not annotated for changes.
3. Deploy same-origin under the same directory to ensure localStorage sharing.
4. Shared state key: proto-note:<requirement-slug>:state:v1; after reading/writing, dispatch an event within the same page; cross-tab listen for storage.
5. URL carries only the business ID; the main content is in shared state. Prefer same-origin; if not, use postMessage and verify the origin.
6. Built-in fixture + "Reset demo data"; upstream/downstream states and exceptions must be reproducible.

Workflow

0. Step 0: Tech stack restoration.
1. Extract change list, platform/page matrix, input branches, and cross-page data relationships from PRD → see references/changeset-schema.md.
2. Collect SDD blockId and write it into each sdd.
3. Build prototypes per platform; for multiple platforms, add a menu, shared state, and verify linkage.
4. Integrate the annotation layer:
   • Add data-diff-page to the container; add ids to landing points; implement DIFF_HOOKS.locate / setDemoState.
   • Move review tabs into meta.demoControls.
   • Write branches into examples (must match fixtures).
   • Before </body>, inline DIFF_CHANGESET, then copy the entire latest assets/diff-annotator.js (do not reuse an outdated copy).
5. Deployment & self-check:

   • Intranet first: If existing intranet static hosting is available, upload there; if the object key would not be overwritten, use a new path (e.g., -v2), returning the URL + md5.

   • GitHub Pages fallback: When intranet is unavailable, publish to a personal repository. First run gh auth status; if unauthorized, communicate and complete gh auth login; do not push to a private repo without authorization:

     bash ~/.cursor/skills/proto-note/scripts/deploy_github.sh <slug> ./index.html
     

Self-Check Checklist

• When restoration is possible, used the online real component library/specification; when not, documented the reason and proceeded with free selection fallback
• Published to intranet first; when intranet unavailable, published to personal GitHub after authorization
• Compared screen-by-screen with the online version (if an online page exists: column widths, frozen columns, action column, pagination, top bar)
• Initially no anchor points/connectors; modules not toggled; newly added modules visible by default to returning visitors
• Toggling a module displays only the corresponding cards/anchor points/connectors and auto-locates; changes within pop-ups automatically open the window with connectors above the pop-up
• No anchor point drift on scroll; no connectors by default; only one connector on fix/hover; fixed state is not overridden by hover
• When the annotation bar is open, horizontal scrolling shows the full right side; horizontal scroll position is not reset by DOM updates; pop-ups scroll with the underlying page in both axes
• target:null has no anchor point; the card is in "Processes & Linkages" and is placed at the end; "Before" always reflects current online status; no missing annotations
• Annotation card SDD deep link opens and locates to the corresponding section
• Demo state is only in the annotation bar; examples are reproducible; download format is correct
• Multi-platform menu is reachable; cross-prototype read/write/refresh/cross-tab/reset are consistent
• Annotation bar collapses cleanly; business interaction is unaffected

References

• This repository README.md (screenshots, Live demo, default plan explanation)
• Live demo: https://pessimistcamellia.github.io/non-ecommerce-thirdparty-order-prototype/admin-upload.html