Citado Viewer Review

Use this skill for changes in:

• packages/fe/src/features/viewer
• packages/viewer-core
• packages/viewer-pdf
• packages/viewer-image

The goal is to catch the recurrent failure patterns already recorded in docs/skills/think.md before they escape into a second-round correction.

Required context

Before reviewing or implementing:

• Read specs/struct.yaml to confirm package boundaries.
• Read .github/instructions/viewer.instructions.md for viewer-specific runtime rules.
• Use ui-design-ref if the change affects visible viewer UI.
• Use webapp-testing when behavior depends on layout, hit testing, overlay stacking, drag affordances, or browser-console cleanliness.
• Use project-lint after edits.

Review workflow

1. Scope the package graph

• Identify whether the change lives in host FE code, shared viewer contracts, or a concrete plugin runtime.
• If a contract in viewer-core changes, inspect downstream assumptions in packages/fe, viewer-pdf, and viewer-image.

2. Audit layering and geometry

• Check stacking-context ancestors before raising z-index.
• When a panel moved sides or changed between flow layout and overlay, audit rail root width, overlay anchor basis, connector origins, and overflow/clipping ancestors together.
• If an overlay must always outrank document or mark layers, verify whether a portal or top-layer mount is required.
• Audit viewer-level footer, header, search panel, and sibling side-panel relations together instead of reviewing them as isolated columns.
• For fullscreen work, verify that the chosen target is the actual workspace or viewer host root, not only the renderer document container.
• For narrow rail interactions, review icon size baseline, hover information carrier, locate behavior, and drag affordance/drop target as one cluster.

3. Audit event and drag chains

• For DragOverlay, keep exactly one visual source visible during drag.
• For pointer capture flows, verify pointerup, pointercancel, lostpointercapture, and window blur cleanup as one set.
• For keyboard overrides, confirm that the browser default is intercepted at the correct event phase.

4. Audit stores and runtime lifecycle

• useSyncExternalStore snapshots must keep stable references across no-op reads.
• Separate renderer initialization/destruction from document or source changes.
• Do not put unstable host callback objects into init effects.
• Prefer leaf-package runtime tests for lifecycle or source-resolution bugs.

5. Audit cross-viewer divergence

• Do not assume PDF and image/canvas viewers share the same geometry or refresh timing model.
• Verify whether an engine-specific runtime switch can disable the event surface even when the exported contract looks correct.
• When connecting shared annotation features to a new viewer, verify tool availability, writable interaction surface, and default layer readiness together.
• For shape-tool bugs, verify draft input, constraint, commit normalization, and final render instead of only the final path.
• For search or navigation jumps, check whether a single resolved anchor can replace a multi-stage page-jump and retry-scroll chain.

6. Perform browser validation when needed

• For annotation/text layers, overlays, hit areas, drag affordances, or console warnings, validate in a real browser instead of relying on typecheck alone.
• For PDF annotation/text layers specifically, confirm non-zero hotspots and clean destroy-time console output.

Output expectations

If you are reviewing:

• Present findings first, ordered by severity.
• Include the missing validation step when a bug is only partially proven.
• If no findings are found, say so explicitly and list any residual runtime gaps.

If you are implementing:

• Use the checklist above before final verification.
• If you uncover a new repeated pattern, trigger think-notes and update the closest durable resource in the same task when practical.

Minimum verification

• Run the package-local pnpm run check for each touched viewer package.
• Use the root pnpm viewer:check when the change spans multiple viewer packages or shared viewer contracts.
• When the bug is layout-, overlay-, or runtime-console-specific, add browser validation and use pnpm viewer:smoke when it is the closest existing smoke coverage.