ssgoi: Skill for Claude Code

You understand the recording; the numerical tool measures it. The user's current request takes precedence over older plans in plans/motion-analyzer/.

The tool is apps/dev/tools/motion-analyzer/run.sh relative to the SSGOI repository root. It uses FFmpeg, a private Python environment (3.9–3.14), and the installed workspace's esbuild to check every fitted curve against the current SSGOI TypeScript. Run pnpm install if workspace dependencies are missing. First use creates the private Python environment; no API key or external video upload is needed. bash apps/dev/tools/motion-analyzer/run.sh synth --out OUTPUT/demo renders a demo recording with known physics if you need to try the tool before a real recording exists.

1. Run bash apps/dev/tools/motion-analyzer/run.sh inspect VIDEO --out OUTPUT/inspection. Read inspection.json and view the contact sheets. Activity intervals are proposals: distinguish navigation, drag/release, loading, scrolling, taps, and system UI yourself.
2. Inspect uncertain parts with inspect VIDEO --out OUTPUT/detail --range START_MS END_MS --step-ms 50. Use actual PTS labels. Split or merge intervals from visual evidence; don't ask the user to cut them unless the content is unavailable.
3. Write a semantic analysis plan using the protocol. Name elements, roles, and anchor ROIs from frames you saw. Keep visual interpretation and geometric assumptions explicit. Incoming ROIs usually belong on the end frame, outgoing on the start frame. Inspect that exact anchor before specifying coordinates. Coordinates are original, rotation-corrected recording pixels. When a page starts off screen or ends covered and you know the layout's travel (a full screen width, a third of it), supply offsetFromEnd / offsetToStart; otherwise the fit infers that rest position and says so.
4. Run bash apps/dev/tools/motion-analyzer/run.sh measure VIDEO --plan PLAN.json --out OUTPUT/report. Empty element lists request automatic geometric proposals. Named elements request only those tracks. Revise the plan if tracking or segmentation is wrong, then rerun.
5. Open the generated report.html viewer: video and graph share a playhead, with frame stepping, speed/loop controls, element selection and a curve/Bezier view. Check source frames and residuals, plus report.json for unmeasured regions, fit error, alternatives, inferred endpoints and physicsVerification. Match visual identity before interpreting a low RMSE. Deliver the viewer and a representative view inline. Use pnpm motion:render PATH/report.json for presentation-only changes; it preserves the measurements. Local file URLs work in a browser. For an in-app browser, run pnpm motion:view OUTPUT_FOLDER and open the printed localhost URL; this server supports the byte ranges needed for video seeking.

Use different physical tracks when properties have different timing. Bezier fits are displayed as references; the reproduction settings must come from SSGOI spring/doubleSpring/inertia. Never call an extrapolated invisible portion a pixel measurement, or claim an arbitrary recording reveals unique source parameters. Include a visible-range result when its initial state is unidentifiable. For a release phase, isolate it and supply a measured/explicit normalized initial velocity with --initial-velocity; do not fit finger-driven drag and free motion as one spring.

Choose the measurement method to match the element: features for textured objects and similarity transforms, edge for a contrasting panel boundary, alpha for a static endpoint mixture. Inspect whether content moves inside a container before treating its feature motion as page displacement. The numerical tools are reusable from Python for other vision algorithms; semantic decisions do not need to be forced through automatic region proposals.

motion.ts starts with a preset override that retunes the registered out / in children of any page preset (axis, drill, fade, sheet, ...) with the measured integrators and their measured start threshold. Hand that to the user first; it is what they paste into axis({ type: "x" }, { override }). The rest of the file lists every measured element with its integrator, delay and source endpoints for a custom transition; bind those to actual DOM geometry in CSS pixels. Blur, perspective, masked morphs, and moving opacity can require separate implementations; say which measurements are observable.